@tp/tp-block-writer (1.0.4)
Installation
@tp:registry=https://gitea.codeblob.work/api/packages/tp-elements/npm/npm install @tp/tp-block-writer@1.0.4"@tp/tp-block-writer": "1.0.4"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>
`;
Embeds render as sandboxed, credentialless iframes (no top navigation, no
cookies) and only for https URLs outside the page's own origin. The host page
must also allow the embed origins in its CSP frame-src — otherwise Chrome
swaps the frame for its own "This content is blocked" page and sends no
request. Cross-origin-isolated hosts (COEP) work in Chromium because of
credentialless; engines without it block embeds that don't send their own
COEP header.
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, checked after the built-in rule (https only, never the page's own origin). URLs that fail 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, credentialless 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 |