tp-elements

@tp/tp-block-writer (1.0.1)

Published 2026-11-14 23:13:45 +01:00 by pk

Installation

@tp:registry=https://gitea.codeblob.work/api/packages/tp-elements/npm/
npm install @tp/tp-block-writer@1.0.1
"@tp/tp-block-writer": "1.0.1"

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>
`;

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 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 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-14 23:13:45 +01:00
1
trading_peter
Apache-2.0
65 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