Replace the TipTap block's paragraph/heading options with configurable textBlocks

[VPS-Andreas]

The text block type select could only offer a fixed paragraph entry plus every enabled heading level, in a fixed order. A design that wants two entries for the same tag — a display headline above a regular heading 1 — or a different order could not be configured.

textBlocks configures the entries explicitly and decouples a text block from the tag it is stored as:

createTipTapRichTextBlock({
    textBlocks: [
        { name: "paragraph", label: "Paragraph", tag: "p" },
        { name: "display", label: "Display", tag: "h1" },
        { name: "heading-1", label: "Heading 1", tag: "h1" },
        { name: "heading-2", label: "Heading 2", tag: "h2" },
    ],
    defaultTextBlock: "paragraph",
});

Two entries on the same tag only stay apart if the content records which one the editor picked, so paragraphs and headings are stored as a single textBlock node that names its entry. The tag is not stored at all — it follows from the configuration. The name is therefore the only thing content carries, and a node's type, its level and its text block can no longer drift apart.

The site renders by that name instead of by heading level:

const nodeMapping: Record<string, TipTapNodeHandler> = {
    textBlock: ({ node, children }) => <Typography variant={textBlockToVariant[node.attrs?.textBlock]}>{children}</Typography>,
};

Content written before this change — paragraph and heading nodes carrying a level — is converted when the block is loaded, by a vendor migration (#6401). A project needs no migration of its own. Its own migrations run after Dextinity's and therefore see the converted nodes, so one written against { type: "heading", attrs: { level } } has to match { type: "textBlock", attrs: { textBlock } } instead.

Because every text block is the same node now, a list item's content expression can no longer keep a heading out of it. The editor takes the content out of the list when a heading is chosen there, turns a heading back into a paragraph when it is wrapped in a list, and the API rejects a heading text block inside a list item.

First of four stacked pull requests: #6383 moves the styles into the text blocks, #6384 adds defaultStyle, #6385 splits the block's Storybook stories by topic.

Example

createTipTapRichTextBlock.test.ts/.test.tsx cover the configuration, the stored format and what a list item accepts, buildTextBlockNodeMigration.test.ts the conversion. In Storybook:

• Heading Levels
• Heading Only
• Heading Only With Text Block Styles
• List Text Block

Session: https://claude.ai/code/session_f3c6ad37-c68b-4187-85b6-2abe5aa95c35

[VPS-Obi]

@greptileai review

[greptile-apps]

Confidence Score: 5/5

The pull request appears safe to merge; the latest changes fully address the remaining list-item validation issue without introducing a new actionable defect.

Summary

This PR replaces separate TipTap paragraph and heading nodes with configurable named textBlock nodes.

• Adds matching API and Admin configuration, schema extensions, validation, editor normalization, and migration behavior.
• Supports multiple named text blocks sharing the same semantic tag.
• Updates DraftJS conversion, site rendering, documentation, fixtures, stories, and tests.
• The changes since the previous review correctly close the unnamed-default list validation gap.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[TipTap JSON content] --> B{Node is textBlock?}
    B -- No --> F[Recursively validate children]
    B -- Yes --> C{Explicit textBlock name?}
    C -- Yes --> D[Resolve configured entry by name]
    C -- No --> E[Use configured defaultTextBlock]
    D --> G{Entry exists?}
    E --> G
    G -- No --> H[Reject content]
    G -- Yes --> I{Inside list item?}
    I -- No --> F
    I -- Yes --> J{Configured tag is p?}
    J -- No --> H
    J -- Yes --> F

Loading

_{Reviews (4) · Last reviewed commit: "Reject an unnamed text block inside a li..."}

[VPS-Obi]

@VPS-Andreas the lint workflow fails.

[VPS-Obi]

The tag is not stored at all — it follows from the configuration.

If the tag isn't stored, why do we need to configure it in the Admin and API?

[VPS-Obi]

If the tag isn't stored, why do we need to configure it in the Admin and API?

@greptileai can you explain?

[greptile-apps]

The tag is configuration, not content data. The stored textBlock name is a stable semantic choice; Admin/API resolve that name through their configured { name, tag } entry whenever they need the tag.

• Admin: uses tag to build the TipTap schema and render/edit nodes as <p> or <h1>–<h6>. It also determines whether a text block is valid inside a list item and how pasted HTML is parsed.
• API: uses the same mapping to validate names, reject heading text blocks inside lists, preserve heading levels for search indexing, migrate legacy paragraph/heading nodes, and interpret the content consistently.
• Site: does not need the complete configuration for the built-in names because its default renderer knows that heading-1 maps to h1, and so on. Custom names or tags require a custom textBlock handler.

Keeping the tag out of each node prevents contradictory data such as a heading-1 text block carrying a separate stale level. Admin and API still need the tag as the shared schema and interpretation contract, and their configurations must match so the same stored name has the same meaning everywhere.