Add defaultTextBlockStyles option to createTipTapRichTextBlock

[VPS-Andreas]

Summary

The text block style dropdown always offered an unstyled Default entry next to the configured textBlockStyles, even for a tag where every instance should always carry one of them, unlike the Draft.js RTE's standardBlockType, which had no such state for the block types it covered.

defaultTextBlockStyles assigns a default style per tag instead: no Default entry is offered for it, a newly created or converted heading/paragraph of that tag gets the style automatically, and the API rejects stored content of that tag missing a style. migrateFromDraftJs falls back to the configured default when a mapped Draft.js block doesn't specify a textBlockStyle. A tag without an entry keeps today's behavior.

A migration that runs after migrateFromDraftJs (for instance one that changes a node's heading level) can leave a node missing its default style, or carrying a style that no longer applies to its new tag, since earlier steps only resolve defaultTextBlockStyles against the tag a node has at that point. A migration is now always appended last to fill in any default still missing, or swap in the default for a style that no longer applies, once every other migration — including a block's own — has applied, so the guarantee holds regardless of what happens in between.

This replaces #6225 (requireTextBlockStyle, a single boolean forcing every applicable tag to require a style, with an implicit "first-in-array-wins" default) and #6004 (defaultTextBlockStyleLabel, a cosmetic rename of the "Default" entry) with one explicit, per-tag mapping — both had grown unclear in scope. Built on top of #6240 (heading-only blocks), now merged.

Example

createTipTapRichTextBlock({
    textBlockStyles: [
        { name: "copy100", appliesTo: ["paragraph"] },
        { name: "copy200", appliesTo: ["paragraph"] },
        { name: "headline300", appliesTo: ["heading-2"] },
    ],
    defaultTextBlockStyles: {
        paragraph: "copy100",
        "heading-2": "headline300",
    },
});

Test plan

• tsc and eslint pass for both packages
• New Storybook story (blocks/TipTapRichTextBlock → "Default Text Block Styles") verified interactively via Playwright — initial default applied, no Default entry for tags with a default, auto-assign on type switch, Default still offered for a tag without a configured default: https://69df3371c46abe69b5199825-nuucasmmou.chromatic.com/?path=/story/blocks-tiptaprichtextblock--default-text-block-styles
• Migration safety net verified end-to-end via migrateBlocks against the demo's Draft.js fixture data, and covered by 4 new tests in buildApplyDefaultTextBlockStylesMigration.test.ts, including a node whose tag change (via a later migration) makes its already-set style inapplicable
• Rebased onto main now that cms-admin: Fix invalid DOM nesting in textBlockStyles node views #6363 and cms-admin: Don't insert a trailing paragraph after a heading #6364 (the two independent TipTap bugfixes found while testing this) are merged
• Still marked draft: open on whether Add requireTextBlockStyle option to TipTap rich text block #6225/TipTap: Allow customizing the default text block style label #6004 should be closed in favor of this

🤖 Generated with Claude Code

[VPS-Obi]

What do you think about this alternative API?

createTipTapRichTextBlock({
    textBlockStyles: [
        { name: "copy100", appliesTo: ["paragraph"], defaultFor: ["paragraph"] },
        { name: "copy200", appliesTo: ["paragraph"] },
        { name: "headline300", appliesTo: ["heading-2"], defaultFor: ["heading-2"] },
    ],
});

[VPS-Andreas]

One case worth checking this against: a style that should be the default for several tags, e.g. copy100 for both paragraph and heading-2.

With defaultFor on the style, appliesTo and defaultFor end up listing the same tags twice on one object:

{ name: "copy100", appliesTo: ["paragraph", "heading-2"], defaultFor: ["paragraph", "heading-2"] }

And nothing stops two different style entries from both claiming defaultFor: ["paragraph"] — that conflict could only be caught with validation across all entries.

With defaultTextBlockStyles: Partial<Record<Tag, string>>, the same case is just the same style name under two keys:

defaultTextBlockStyles: {
    paragraph: "copy100",
    "heading-2": "copy100",
},

Since it's a Record, TypeScript already enforces exactly one default per tag — the conflict defaultFor would need runtime validation for can't happen here. I'd keep the current API.

[VPS-Andreas]

Closed in favor of #6382, #6383, #6384