tp-elements

@tp/tp-block-writer (1.0.4)

Published 2026-11-15 20:29:16 +01:00 by pk

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

Block based rich content editor system (Notion-style) built with Lit web components.

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. See docs/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 survive structuredClone / 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 with allowsChildren: 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 with blockRegistry.register(...) and define a custom element.
  • Theme it → docs/theming.md. Set --tpbw-* custom properties via a CSS class or inject a stylesheet programmatically with setTheme(), and override icons with setIcons().

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
Details
npm
2026-11-15 20:29:16 +01:00
105
trading_peter
Apache-2.0
latest
67 KiB
Assets (1)
Versions (5) View all
1.0.4 2026-11-15
1.0.3 2026-11-15
1.0.2 2026-11-15
1.0.1 2026-11-14
1.0.0 2026-06-13