@tp/tp-block-writer (1.0.2)
Installation
@tp:registry=https://gitea.codeblob.work/api/packages/tp-elements/npm/npm install @tp/tp-block-writer@1.0.2"@tp/tp-block-writer": "1.0.2"About this package
tp-block-writer
A block-based rich content editor in the spirit of Notion, built as composable
Lit web components for the tp-elements library. A
document is a list of blocks that can be created, edited, transformed,
reordered, nested and deleted. Inline text formatting is delegated to
tiptap (the same engine tp-rich-text-box uses).
Design goal: composability. Every block is a self-contained web component, so wrapping an existing
tp-*element (chart, table, …) in a new block is a few dozen lines of glue code. Seedocs/custom-blocks.md.
For the full design rationale, document model and roadmap, read
SPEC.md. This README is the practical getting-started guide; the
deeper tutorials live in docs/.
Documentation map
| Document | Read it for |
|---|---|
| README.md (this file) | Install, quick start, public API, document model. |
docs/custom-blocks.md |
Step-by-step tutorial: build a non-textual block and a textual block, register it, wire markdown shortcuts. |
docs/theming.md |
Step-by-step tutorial: author a CSS theme (custom properties + parts) and an icon set. |
SPEC.md |
Architecture, operations model, keyboard semantics, milestones, design decisions. |
Install
npm install @tp/tp-block-writer
Peer/runtime dependencies (resolved automatically): lit, @tiptap/*,
@floating-ui/dom, @tp/helpers, @tp/tp-icon, @tp/tp-checkbox.
Quick start
Importing the package entry registers the <tp-block-writer> element and
all built-in blocks (paragraph, heading, list/todo, quote, divider, code,
image, callout, toggle, table, embed):
import '@tp/tp-block-writer/tp-block-writer.js';
<tp-block-writer></tp-block-writer>
That is the entire zero-config setup. Type / for the block menu, use markdown
shortcuts (# , - , 1. , [] , > , ```, ---), press Tab /
Shift+Tab to nest, select text for the inline format bubble, and drag blocks
by the handle in the left gutter.
With a document and a value listener
value is the document JSON (see Document model). The
editor emits value-changed (debounced) for persistence and doc-changed
(synchronous, per operation batch) for op-level integrations.
import '@tp/tp-block-writer/tp-block-writer.js';
const writer = document.querySelector('tp-block-writer');
writer.value = {
version: 1,
blocks: [
{ id: 'b_intro001', type: 'heading', props: { level: 1 },
content: { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Hello' }] }] },
children: [] },
{ id: 'b_intro002', type: 'paragraph', props: {},
content: { type: 'doc', content: [{ type: 'paragraph' }] },
children: [] },
],
};
writer.addEventListener('value-changed', e => {
localStorage.setItem('doc', JSON.stringify(e.detail.value));
});
In a Lit template the same thing is just property bindings:
html`
<tp-block-writer
.value=${doc}
.uploadAdapter=${uploadAdapter}
.embedAllowlist=${['youtube.com', 'vimeo.com']}
@value-changed=${e => this.save(e.detail.value)}
></tp-block-writer>
`;
Read-only rendering
The same components render the document; there is no separate renderer.
<tp-block-writer readonly .value=${doc}></tp-block-writer>
Embedded / compact mode
compact tightens spacing for small surfaces (cards, forms):
<tp-block-writer compact .value=${doc}></tp-block-writer>
Public API
Properties
| Property | Type | Notes |
|---|---|---|
value |
Object |
The document JSON. Also the FormElement value, so the editor participates in tp-form serialization. |
allowedBlocks |
string[] |
Optional filter — only these block types appear in the slash menu for this instance. |
readonly |
Boolean (reflected) |
Hides chrome, disables editing. |
compact |
Boolean (reflected) |
Denser gutter/spacing for embedded use. |
placeholder |
String |
Placeholder text for empty paragraphs. Default: Type '/' for commands. |
uploadAdapter |
Object |
{ upload(file, onProgress): Promise<{ url }> } — used by image blocks. Without one, picked files fall back to inline data URLs. |
embedAllowlist |
string[] | (url) => boolean |
Gate for embed <iframe>s. URLs that fail it render a plain link card. |
highlighter |
(code, lang) => string |
Optional code-block syntax highlighter. |
Methods
| Method | Returns | Notes |
|---|---|---|
getDoc() |
Object |
Deep clone of the current document. |
setDoc(doc) |
— | Replace the document (equivalent to setting value). |
focus() |
— | Focus the first textual block. |
insertBlock(type, props?, index?) |
string (new block id) |
Insert a block at root level (default: at the end). |
undo() / redo() |
— | Document-level history (works regardless of which block has focus). |
validate() |
boolean |
FormElement hook — true unless required and the document is empty. |
TpBlockWriter.migrate(doc) |
Object |
Static. Upgrade an older document to the current shape. |
Events
All events are composed and bubbling; payload is in event.detail.
| Event | detail | When |
|---|---|---|
value-changed |
{ value } (full doc) |
Debounced (~300 ms) after any change — form/persistence hook. |
doc-changed |
{ ops, doc } |
Synchronous, per operation batch — for op-based sync. |
editor-ready |
{} |
First render complete. |
Document model
{
version: 1,
blocks: [
{
id: 'b_8f3kz01x', // stable, unique within the doc, generated once
type: 'heading', // registry key
props: { level: 2 }, // block-type-specific, JSON-serializable
content: { /* tiptap JSON doc, inline-only */ }, // textual blocks only
children: [] // ordered child blocks (any type)
}
]
}
id—b_+ random base36; never regenerated on edit, regenerated on paste/duplicate. Stable IDs exist for block links and future CRDT sync.props— must survivestructuredClone/JSON.stringify(no functions, no DOM nodes).content— present only on textual blocks; a tiptap JSON document restricted to inline content.children— present on every block (may be empty). Most block types may nest children; a definition can opt out withallowsChildren: false.
Mutations never splice the array directly — they go through operations
(insertBlock, removeBlock, moveBlock, updateProps, replaceContent,
transformBlock), each of which produces an inverse for undo/redo and is
emitted on doc-changed. See SPEC.md §4 for the full model.
Unknown blocks are preserved
A document containing a block type that is not registered (e.g. a plugin was
uninstalled) is not discarded: it renders via a fallback tpbw-unknown
block and round-trips untouched through save/load.
Built-in blocks
| Type | Tag | Key props | Notes |
|---|---|---|---|
paragraph |
tpbw-paragraph |
— | Default block. |
heading |
tpbw-heading |
level: 1|2|3 |
#/##/###. |
list-item |
tpbw-list-item |
kind: 'bullet'|'number'|'todo', checked? |
One element for all three kinds. - , 1. , [] . |
quote |
tpbw-quote |
— | > . |
divider |
tpbw-divider |
— | ---. Not textual, no children. |
code |
tpbw-code |
language, code |
```. Optional host highlighter. |
image |
tpbw-image |
src, alt, width? |
Uses uploadAdapter; URL paste works without one. |
callout |
tpbw-callout |
icon, tone |
Tinted box, textual + children. |
toggle |
tpbw-toggle |
collapsed |
Collapsible; children are the body. |
table |
tpbw-table |
rows, headerRow |
Inline-rich cells stored in props. |
embed |
tpbw-embed |
url, height? |
Sandboxed iframe only if allowlisted. |
unknown |
tpbw-unknown |
passthrough | Fallback for unregistered types. |
To restrict which blocks an instance offers, set allowedBlocks:
<tp-block-writer .allowedBlocks=${['paragraph', 'heading', 'list-item', 'image']}></tp-block-writer>
Extending
- Add a block →
docs/custom-blocks.md. Register a definition withblockRegistry.register(...)and define a custom element. - Theme it →
docs/theming.md. Set--tpbw-*custom properties via a CSS class or inject a stylesheet programmatically withsetTheme(), and override icons withsetIcons().
Demo
# Serve the repo root with any static server, then open:
demo/index.html
The demo (demo/src/the-app.js) shows two editors side by side (default and
Terminal-dark themes), a working upload adapter, an embed allowlist, JSON
dump/load, and a read-only toggle.
License
Apache-2.0 © trading_peter
Dependencies
Dependencies
| ID | Version |
|---|---|
| @floating-ui/dom | ^1.6.0 |
| @tiptap/core | ^3.0.0 |
| @tiptap/extension-bold | ^3.0.0 |
| @tiptap/extension-code | ^3.0.0 |
| @tiptap/extension-document | ^3.0.0 |
| @tiptap/extension-hard-break | ^3.0.0 |
| @tiptap/extension-italic | ^3.0.0 |
| @tiptap/extension-link | ^3.0.0 |
| @tiptap/extension-paragraph | ^3.0.0 |
| @tiptap/extension-strike | ^3.0.0 |
| @tiptap/extension-text | ^3.0.0 |
| @tiptap/extension-underline | ^3.0.0 |
| @tiptap/extensions | ^3.0.0 |
| @tp/helpers | ^2.7.1 |
| @tp/tp-checkbox | ^1.1.0 |
| @tp/tp-icon | ^1.0.2 |
| lit | ^3.0.0 |