API dokumentace

Nibble je rozdělený do tří balíčků: @nibble/core (model, výběr, historie, příkazy, registr ovládání), @nibble/ui (lišta, nabídka, dialogy, CSS) a @nibble/plugins (odkazy, obrázky, tabulky, videa, nástroje, písma). Jádro běží i bez lišty — hodí se to v testech a při dávkovém zpracování obsahu.

Instalace

git clone https://github.com/svatekr70/nibble
npm install
npm run build

Build vytvoří ESM bundly a stylopis. Do stránky se vkládají takhle:

import { Nibble } from '@nibble/core'
import { attachToolbar } from '@nibble/ui'
import '@nibble/ui/nibble.css'

Bez balíčkovače (CDN)

Sestavená knihovna je jeden soubor se vším, co je v core, ui i plugins. Nic se neinstaluje a nic se nesestavuje — stačí adresa:

<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/gh/svatekr70/nibble@v0.5.0/dist/nibble.css">

<div id="obsah"><p>Ahoj.</p></div>

<script type="module">
  import { Nibble, attachToolbar, link, image, table }
    from 'https://cdn.jsdelivr.net/gh/svatekr70/nibble@v0.5.0/dist/nibble.min.js'

  const editor = await Nibble.create({
    target: '#obsah',
    plugins: [link, image, table],
  })
  attachToolbar(editor, { menubar: true })
</script>

Je to modul, takže <script> musí mít type="module".

Proto je dist/ v repozitáři, i když se sestavuje: jsDelivr servíruje soubory přímo z tagu a bez commitnutého buildu by ta adresa neexistovala. Že bundle sedí se zdrojem, hlídá CI — po sestavení musí být pracovní strom čistý.

Totéž leží i tady na webu (https://svatekr70.github.io/nibble/dist/nibble.min.js), jen je to vždy poslední stav hlavní větve. Jednotlivé balíčky jdou z webu načíst i zvlášť — dist/core/src/index.js, dist/ui/src/index.js, dist/plugins/src/index.js — když nechcete tahat všechno.

Rychlý start

import { Nibble } from '@nibble/core'
import { attachToolbar } from '@nibble/ui'
import { link, createImagePlugin, table } from '@nibble/plugins'
import '@nibble/ui/nibble.css'

const editor = await Nibble.create({
  target: '#obsah',
  schema: 'legacy',
  plugins: [
    link,
    createImagePlugin({
      // Bez adaptéru se obrázek vloží jako data: URL.
      upload: async (file) => {
        const body = new FormData()
        body.append('file', file)
        const res = await fetch('/api/upload', { method: 'POST', body })
        return (await res.json()).url
      },
    }),
    table,
  ],
})

attachToolbar(editor)

editor.on('change', ({ html }) => uloz(html))

Při napojení na <textarea> zůstává textarea zdrojem pravdy pro odeslání formuláře — stačí vyměnit jeden řádek a odesílání funguje dál.

Nibble.create()

Vrací Promise, protože pluginy smí mít asynchronní přípravu (třeba načtení seznamu písem). Existuje i pojmenovaný export create() se stejným chováním.

target je CSS selektor, prvek nebo <textarea>. U textarey se převezme její obsah, textarea se schová a při každé změně se do ní zapisuje výsledek — odeslání formuláře pak funguje beze změny v backendu.

Přehled voleb

Schema

Schema říká, co smí kde být. Dva režimy:

Srovnávání tvaru je líné: běží jen na tom bloku, do kterého uživatel opravdu zasáhl. Načtený dokument se nikdy nepřepisuje jen proto, že by se dnes zapsal jinak.

Zkontroluje obsah proti schématu, aniž by cokoli měnil. Bez argumentu kontroluje aktuální obsah editoru. Hodí se na dávkovou revizi databáze před migrací.

Vkládání

await Nibble.create({
  target: '#obsah',
  paste: {
    keepStyles: ['color', 'background-color', 'text-align'],
    markdown: true,
  },
})

Zdroj vloženého obsahu se rozpoznává a čistí se podle něj. Událost pasteclean nese, co se stalo:

editor.on('pasteclean', ({ source, removed }) => {
  // source: 'word' | 'gdocs' | 'libreoffice' | 'html' | 'text'
  console.log(source, removed)
})

Vložené rámce

<iframe> je jediná značka, která do stránky pouští cizí kód. Nibble ho proto neřeší seznamem zakázaného, ale seznamem povoleného — co v něm není, se zahodí:

await Nibble.create({
  target: '#obsah',
  // Prázdné pole zakáže rámce úplně.
  allowedEmbedHosts: ['youtube.com', 'youtube-nocookie.com', 'vimeo.com'],
})

Bez uvedení platí DEFAULT_EMBED_HOSTS — běžné videoslužby. Kontrola porovnává hostitele včetně poddomén, ne podřetězec v URL.

Obsah

Serializovaný obsah. Bloky, kterých se nikdo nedotkl, se vypíšou v původním znění — proto je výsledek po pouhém načtení znak po znaku shodný se vstupem.

Nahradí obsah. Zahodí historii oblastí a založí nové snímky, takže záruka round-tripu platí i pro nově nastavený obsah.

Vloží HTML na pozici kurzoru. Obsah projde sanitizací, takže je bezpečné sem poslat i něco, co přišlo zvenčí.

Které uzly nejvyšší úrovně se od načtení změnily. Užitečné při ladění i v testech — demo na tomhle webu jimi ukazuje, kolik bloků úprava opravdu zasáhla.

Stav a služby

Akce a dotazy

editor.exec('link', { href })   // → boolean (šlo to?)
editor.can('link')              // smí se to teď? → stav tlačítka
editor.is('bold')               // je výběr tučný? → aktivní tlačítko
editor.focus()
editor.setMode('design')        // 'design' | 'readonly'
editor.destroy()

Proti TinyMCE zmizel globální singleton: žádné nibble.activeEditor. Instanci si drží ten, kdo ji vytvořil.

Pomocné dotazy na aktuální blok používá lišta a hodí se i vlastnímu ovládání:

editor.getBlockTag()      // 'p' | 'h2' | 'blockquote' | null
editor.isInList()         // 'ul' | 'ol' | null
editor.getAlignment()     // 'left' | 'center' | 'right' | 'justify' | ''
editor.currentBlock()     // Element | null

Události

on() vrací funkci pro odhlášení — nemusíte si držet referenci na posluchače:

const off = editor.on('change', ({ html }) => uloz(html))
off()

attachToolbar()

const ui = attachToolbar(editor, {
  layout: [
    ['undo', 'redo'],
    ['bold', 'italic', 'underline'],
    ['link', 'image', 'table'],
  ],
  layoutBottom: [['code', 'fullscreen']],
  menubar: true,
  prefsKey: 'clanky',
  prefs: { height: '500px' },
  settings: true,
})

Vrácené EditorUI nese toolbar, menubar, contextToolbar, prefs a destroy().

Výchozí rozvržení obsahuje: undo redo · blocks fontfamily fontsize lineheight · bold italic underline strike · forecolor backcolor · bullist numlist · alignleft aligncenter alignright alignjustify · link image media table emoji charmap · blockquote hr removeformat · code searchreplace fullscreen. Tlačítko, jehož plugin není načtený, se v liště prostě neobjeví.

Registr ovládání

Plugin si přihlásí ovládací prvek a lišta ho vykreslí. Žádné další zařizování není potřeba — a jádro nemusí o liště vědět.

editor.ui.addButton('zvyraznit', {
  icon: 'forecolor',
  tooltip: 'Zvýraznit',
  shortcut: 'Ctrl+H',
  onAction: () => editor.exec('zvyraznit'),
  isActive: () => editor.is('zvyraznit'),
  isEnabled: () => editor.can('zvyraznit'),
})

editor.ui.get(name) vrátí přihlášený prvek, names() seznam všech. Toho využívá i nastavení, aby nenabízelo tlačítka, jejichž plugin se nenačetl.

Dialogy a hlášky

Dialog se popíše polem polí; vykreslení, ozvučení i validaci obstará lišta. Vrací null, když uživatel dialog zavřel.

const data = await editor.ui.dialog({
  title: 'Vložit odkaz',
  fields: [
    { type: 'url', name: 'href', label: 'Adresa', required: true },
    { type: 'text', name: 'text', label: 'Text odkazu' },
    { type: 'checkbox', name: 'blank', label: 'Otevřít v novém okně' },
  ],
  submit: 'Vložit',
})

if (data) editor.exec('link', data)

Typy polí: text, url, number, select, checkbox, color, textarea, code (velké okno se zvýrazněnou syntaxí) a dvojice emoji / chars (mřížka pojmenovaných znaků s kategoriemi a hledáním; seznam se předává v field.glyphs, liší se jen sazbou políček).

Stav se ukládá i tehdy, když stavový řádek zrovna neexistuje. Když si ho uživatel zapne, hodnoty se do něj přehrají — plugin se nemusí spouštět znovu.

Nastavení uživatele

Rozvržení lišty navrhne programátor, ale poslední slovo má ten, kdo u editoru sedí. Nastavení se ukládá do localStorage a přebíjí konfiguraci.

ui.prefs.get()                     // aktuální nastavení
ui.prefs.set({ sticky: false })      // ovládání se postaví znovu
ui.prefs.layoutFor('top')            // co se vykreslí v prvním řádku
ui.prefs.reset()                   // zpátky podle konfigurace
ui.prefs.onChange(fn)               // vrací funkci pro odhlášení

Dialog nastavení umí vypsat hotovou konfiguraci podle aktuálního stavu — když si uživatel lištu přeskládá tak, že to dává smysl, je to nejlepší podklad pro to, jak má editor vypadat pro všechny ostatní.

Dodávané pluginy

Vlastní plugin

Plugin je objekt se jménem a funkcí setup. Ta dostane celý editor — jakýkoli mezistupeň by musel jen předávat dál. Vrácená funkce je úklid; volá se v destroy(), takže inicializace i úklid stojí na jednom místě.

import type { Plugin } from '@nibble/core'

export const poznamka: Plugin = {
  name: 'poznamka',

  setup(editor) {
    editor.commands.add('poznamka', {
      exec() {
        return editor.insertHTML('<aside class="pozn">…</aside>')
      },
    })

    editor.ui.addButton('poznamka', {
      icon: 'blockquote',
      tooltip: 'Poznámka na okraj',
      onAction: () => editor.exec('poznamka'),
    })

    const off = editor.on('change', spocitejPoznamky)
    return () => { off() }
  },
}

Pluginy s volbami se dělají tovární funkcí — createImagePlugin(), createTablePlugin(), createMediaPlugin(), createFontPlugin() — aby se konfigurace nemusela protahovat globálním stavem.

Serializace a round-trip

Parser si u každé oblasti nejvyšší úrovně pamatuje původní zdroj a snímek DOMu. Serializace pak vypíše zdroj doslova — dokud se DOM od snímku neliší. Znamená to mimo jiné, že:

• entity zůstanou tak, jak byly (  se nepřepíše na mezeru a naopak),
• pořadí a zápis atributů se nemění, včetně uvozovek,
• komentáře, podmíněné komentáře i podivné mezery přežijí,
• úprava jednoho odstavce nepřeformátuje zbytek dokumentu.

Jediná změna, která se dělá vždy, je převod CRLF na LF. Prohlížeč ho udělá sám v textarea.value i při parsování HTML — slib, že se zachová, by se nedal splnit. Pomocná funkce normalizeNewlines() je veřejná, aby šlo porovnávat se stejným základem.

Obojí je dostupné samostatně — hodí se při dávkovém zpracování obsahu mimo editor.

CSS proměnné

Žádný generátor motivů, jen proměnné. Sedí na :root, protože dialogy se vkládají do <body> — mimo obal editoru — a jinak by je nezdědily.

Tmavý režim se řídí prefers-color-scheme a přepisuje stejné proměnné. Kdo chce vlastní vzhled, přebije je ve svém CSS.

Klávesové zkratky

Zkratky pluginů se objevují i v nabídkovém pruhu vedle názvu položky, takže se dají odkoukat bez čtení dokumentace.