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, úkoly, Markdown při psaní). 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.6.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.6.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

bullist a numlist berou nepovinné { type } — data-type nově zakládaného seznamu. Nastaví se dřív, než se seznam slije se sousedy; sousední seznamy se totiž slévají jen při stejném data-type, takže úkoly pod odrážkami zůstanou úkoly.

editor.exec('bullist', { type: 'taskList' })
editor.exec('tasklist')      // tasks: přepne seznam úkolů
editor.exec('details')       // details: obalí označené bloky
editor.exec('detailsopen')   // přepne atribut open
editor.exec('undetails')     // zruší blok, obsah zůstane

Blokové příkazy (nadpis, seznam, citace) v nadpisu rozbalovacího bloku (<summary>) nic neudělají a vrátí false — nadpis je jeden řádek.

Pro pluginy, které reagují na psaní:

Text bloku od začátku po kurzor, i když je blok rozdělený do více uzlů a značek. Na něm stojí Markdown zkratky i lomítková nabídka.

Je v editoru jen jeden prázdný odstavec? Podle toho se ukazuje placeholder.

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 tasklist · 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'),
  active: (ed) => ed.is('zvyraznit'),
  enabled: (ed) => ed.can('zvyraznit'),
})

Nabídka u kurzoru

addSuggestion je obecná verze lomítkové nabídky — jiný znak, jiné položky. Fokus zůstává v editoru: psaní za spouštěčem nabídku filtruje, šipky vybírají, Enter nebo Tab potvrdí, Escape zavře.

import { filterSuggestions } from '@nibble/core'

editor.ui.addSuggestion('mention', {
  trigger: '@',
  items: (ed, query) => filterSuggestions(lide, query),
  onPick: (ed, item) => ed.exec('mention', item.id),
})

Položka (SuggestionItem) má id, label a nepovinně icon a keywords. filterSuggestions(items, query) hledá bez ohledu na diakritiku a velikost písmen a dává napřed položky, jejichž popisek dotazem začíná. suggestionQuery(textBefore, trigger, startOfBlock) vrátí dotaz za spouštěčem, nebo null, když nabídka otevřená být nemá.

Data jsou v jádře, vykresluje je bindCaretMenu(editor) z @nibble/ui. attachToolbar() ho zapojí sám; ručně je potřeba jen bez lišty. Vrací funkci pro úklid.

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. 'over' položku zbarví jako překročenou; tak počítadlo ukazuje limit.

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', (ed) =>
      ed.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

Markdown při psaní

S pluginem markdownShortcuts. Blokové zkratky platí, jen když je vzor celý začátek odstavce:

Řádkové se spouštějí zavírací značkou: **x** tučně, *x* a _x_ kurzíva, `x` kód, ~~x~~ přeškrtnutí. Obsah nesmí začínat ani končit mezerou (2 * 3 * 4 je násobení) a _ uprostřed slova nic nespustí. V kódu a v odkazech se zkratky nespouštějí. První Ctrl+Z převod vrátí a nechá napsaný text.

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