library
Prebuilt pebble components: drop-in custom elements, no compiler needed
Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.
tablet — <pebble-tablet>
A plain-text notes editor. A server-rendered <textarea> is the initial value, the no-JS fallback, the editing surface after the upgrade, and the form field of record throughout — enhancement changes what an edit means, never what the user sees.
<script type="module" src="vendor/pebble-library/tablet.js"></script>
<pebble-tablet>
<textarea name="body">Dear diary,</textarea>
</pebble-tablet>
With no <textarea> child the element renders an empty one, taking the host's name if it has one. With no JS the markup works as it always did.
Props
One, dialect (the attribute of the same name): which registered dialect gives the text its meaning; absent, the text is plain. Everything else the editor needs is already on the textarea: name, placeholder, rows, readonly, disabled, aria-label pass through natively, before and after the upgrade.
Dialects
A dialect is a value a page supplies so the text means something — Markdown-like markers, task boxes, the app's stored format — without the engine knowing any of it. Register it once, by name; any <pebble-tablet dialect="…"> on the page uses it:
import { defineDialect, type Dialect } from "@pebble/tablet";
const notes: Dialect = {
commands: { insertLineBreak: continueList, bold: state => toggleSpan(state, "**") },
keymap: { "Mod+B": "bold" },
decorate: line => ({ kind: "paragraph", segments: [{ text: line, classes: [] }] }),
tick: (state, line) => toggleTask(state, line),
};
defineDialect("notes", notes);
| field | what it is |
|---|---|
commands | (state, text) => Transaction | null, keyed by beforeinput inputType (insertLineBreak, deleteContentBackward, …) or by a chord name from keymap. text is what the input carries — the typed character for insertText, the pasted text for insertFromPaste — and empty for keys and chords. null declines and the plain command runs, so a dialect only states its special cases. The element cancels every inputType a dialect names. |
keymap | extra chords onto command names ("Mod+B": "bold"), merged over the plain ones (Mod+Z, Mod+Shift+Z, Mod+Y, Mod+A). |
decorate | one line onto { kind, segments }. The segments must spell the line exactly, in order (spells(line, decorated) checks it). kind becomes the line's class line-<kind>; each segment's classes its span's classes; a segment with box: { checked } is drawn as a task box. |
tick | the transaction a click on line n's box performs, or null. One undo step. |
Everything a dialect returns goes through the engine: its edits are transactions, recorded in history, mirrored to the field, and announced by change like any other.
Enter in a textarea is insertLineBreak, not insertParagraph (that one is contenteditable's). A dialect that continues lists on Enter keys its command on insertLineBreak; Shift+Enter fires the same inputType, so it continues too.
A dialect defined after the element upgraded — the usual order, since importing the bundle upgrades the page at once — applies from the moment it is defined. The registry is global, so a second bundle carrying tablet shares it.
The backdrop: decoration without leaving the textarea
When the dialect decorates, the host gets data-decorated and a part="backdrop" layer, aria-hidden, laid over the field's box and painted above it. The field's own glyphs turn transparent; the backdrop spells the same lines in the same font, padding, border width, wrap and scrollbar gutter, so every glyph lands where the field's would have. The field is still the surface: caret, selection, IME, spellcheck, mobile keyboards and assistive technology all keep talking to a real <textarea>. The backdrop only paints; its task boxes are the only part of it that takes a click (the press never moves focus off the field).
The rule this imposes on a page's decoration CSS: never change a glyph's advance width. Colour, background, underline, opacity, borders and outlines that take no space are fine. font-size, font-family, letter-spacing and padding on a span are not. font-weight and font-style are fine only in a font whose widths do not depend on them — set a monospace --tablet-font for that. The smoke test checks the invariant in Chromium pixel for pixel.
Style a dialect's lines and spans from the page:
pebble-tablet[dialect="notes"] {
--tablet-font: ui-monospace, monospace;
}
pebble-tablet [part~="backdrop"] .line-heading-1 { color: var(--accent); font-weight: 700; }
pebble-tablet [part~="backdrop"] .mark { opacity: 0.45; }
Events
Both bubble and cross shadow boundaries; detail carries the text.
| event | detail | when |
|---|---|---|
change | { value } | the document changed, after 300 ms of silence (CHANGE_DEBOUNCE) |
save | { value } | Mod+S inside the editor (the browser's own Save never opens) |
change is the document signal differentiated and debounced — it fires for typing, undo, paste, a programmatic write to the field, a form reset: anything that changed the text, once per quiet period. It does not fire for the initial value.
save resolves through pebble's keys(), which resolves nothing while an IME composition is in progress — the chord never steals a composing keystroke.
Parts and styling
One element, two roles: the textarea carries part="editor field". With a decorating dialect, part="backdrop" is the painted layer and part="box" each task box in it. The stylesheet follows pebble conventions — state as custom properties on the host, never generated CSS:
| property | default |
|---|---|
--tablet-min-height | 4lh |
--tablet-max-height | none |
--tablet-padding | 0.5rem 0.75rem |
--tablet-color | inherit |
--tablet-background | transparent |
--tablet-border | 1px solid color-mix(in srgb, currentColor 25%, transparent) |
--tablet-radius | 6px |
--tablet-caret | currentColor |
--tablet-focus-outline | 2px solid var(--accent, currentColor) |
--tablet-sizing | content — the field fits its text, between the min and max heights; fixed keeps the textarea's rows |
--tablet-resize | none where field-sizing is supported; set vertical with --tablet-sizing: fixed to bring the handle back |
--tablet-font | inherit — the field's and the backdrop's font |
--tablet-selection | color-mix(in srgb, var(--accent, Highlight) 30%, transparent) — decorated only |
--tablet-placeholder | GrayText — decorated only |
--tablet-box | var(--accent, CanvasText) — a task box |
--tablet-box-mark | Canvas — the tick inside a checked box |
The same rules style the textarea before and after the upgrade, so enhancement never reflows.
The field grows with its text (field-sizing: content) from --tablet-min-height until --tablet-max-height, then scrolls. Browsers without field-sizing ignore it and keep the textarea's rows and its resize handle.
The escape hatch
element.editor is a read-only live view of the engine: { doc, selection }. For reading, focus()ing (element.querySelector("textarea").focus()), and tests — not the API.
Why our own engine
tablet's first iteration wrapped CodeMirror 6 (94.9 kB gz). This iteration owns the document. The research that shaped it:
toki2's web/editor/ (primary cue). The paradigm already applied to an editor: DOM events mapped to actions as data (edit/key/select/composed), a pure step reducer folding actions into { state, history }, history as two stacks of whole states grouped by a 500 ms pause, and one toSignal crossing with effects writing outward. tablet generalizes it from toki2's block/markdown engine to plain text: the commands lose the marker/dialect logic, and the surface stops being a contenteditable that must be selection-mapped and re-rendered — it is the textarea itself, so selectionStart/End replace the DOM-position math of dom.ts wholesale. What survives verbatim is the shape: actions carry the selection read at event time, composition folds in as one step at compositionend, and an unchanged input returns the identical model so nothing downstream stirs.
CodeMirror 6. The ideas worth keeping are values, not code: a transaction is a value ({ changes, selection }), state is a value, history is a value, and the view is a pure projection of state — exactly the engine's state.ts. What tablet leaves behind is the machinery CM6 needs for what it is: a document tree with positions mapped through change sets, facet/extension resolution, and a DOM renderer that must display any document a plugin can describe. CM6 cannot use the textarea as its surface because it renders; tablet doesn't render, so the 90 kB of view and state machinery has nothing to do.
CodeJar and textarea-caret-position (the minimal editors). CodeJar (~2.5 kB) edits a contenteditable and re-highlights it on every input; its real cost is the caret save/restore dance across re-renders — machinery that exists only because the DOM is rewritten under the caret. textarea-caret-position exists because a textarea can't tell you where the caret is on screen — needed for @-mention popups, which notes don't have. Both lessons are negative space: if you never re-render the surface and never need caret coordinates, the platform gives you a correct plain-text editor for free. tablet keeps to that: the only writes to the field are the mirror's value =, and the caret is projected back from the model afterwards.
ProseMirror and Lexical (the rich ones). Their size buys a schema-checked document tree, DOM reconciliation, plugins, and collaborative-editing hooks — the machinery of rich text, where the document is a tree of styled nodes and the DOM is an approximation of it that must be kept honest. None of it applies: a plain-text document is a string, the textarea is the platform's own editor for strings, and there is nothing to reconcile. Where those engines fight the browser's contenteditable, tablet cancels the handful of beforeinput types it understands, applies them as exact transactions, and lets everything else fall through to the browser and reconcile by diff. The one thing the platform will not give you is a trustworthy undo: native textarea undo dies at the first programmatic value = write, and the mirror writes constantly. So history is the engine's own — that is its reason to exist.
The architecture in one paragraph
beforeinput/paste/cut/keydown/selectionchange/compositionend are streams. Each event maps to an action — what the event meant, with the selection read off the field at event time. scan(step, …) folds actions into the model; one toSignal crosses; effects only write outward: the field's value through mirror (so a plain FormData read sends what was typed), the caret through afterRender (a value write moves the caret; the projection puts it back before the next event), and change/save through emit. Edits the engine handles are canceled at beforeinput and applied exactly; anything it declines reaches the field natively and reconciles by minimal diff through the input event — the paths are mutually exclusive per edit because preventDefault decides which one runs. IME composition is never canceled: composed text is not finalized text, and it folds into the model as a single undoable step at compositionend.
The engine, for tests
packages/tablet/engine/ is pure — no DOM, no events, no time:
state.ts—{ doc, selection }, transactions as values,apply.commands.ts—insertText,newline,deleteBackward/Forward,deleteWordBackward/Forward,deleteLineBackward/Forward,selectAll; surrogate-pair-safe, line-bounded.history.ts— undo/redo as values; runs of same-group edits inside 500 ms join one step;other(a newline, a paste, a programmatic set) never joins; a selection move closes the open group.model.ts— the action vocabulary andstep, the only reducer;stepWith(dialect)is the same reducer with a dialect's commands consulted first.dialect.ts— theDialectshape,plain, andspells.
Correctness lives in packages/tablet/engine/*.test.ts (pure, fast); the element tests in test/tablet.test.ts drive synthetic events through happy-dom; true native typing is owned by the headless-Chromium smoke (examples/tablet-smoke.ts).