Change default list item rendering to skip paragraph tags (breaking change)

[Copilot]

Problem

When ProseMirror/TipTap generates HTML from JSON, list items automatically contain paragraph tags, resulting in output like:

<ul><li><p>huhu</p></li><li><p>hahaha</p></li><li><p>hihi</p></li></ul>

This makes styling difficult as the extra <p> tags inside <li> elements are often undesirable. The expected output for simple list items should be:

<ul><li>huhu</li><li>hahaha</li><li>hihi</li></ul>

Solution

This PR changes the default behavior to render list items without paragraph tags for cleaner HTML output. Users who need the previous behavior can opt-in using the setWrapParagraphsInListItems(true) method.

Breaking Change - Version 2.x

The default rendering behavior has changed from version 1.x to 2.x:

• Version 1.x: <ul><li><p>text</p></li></ul> (paragraphs wrapped in list items)
• Version 2.x: <ul><li>text</li></ul> (clean list items by default)

Migration Guide

If you need to restore the version 1.x behavior with paragraph tags in list items:

$parser = new \Nadar\ProseMirror\Parser();
$parser->setWrapParagraphsInListItems(true);
$html = $parser->toHtml($json);

See UPGRADE.md for complete upgrade details from 1.x to 2.x.

Key Features

• Cleaner HTML by default: List items render without unnecessary paragraph tags
• Opt-in for legacy behavior: Use setWrapParagraphsInListItems(true) to restore previous behavior
• Selective: Only affects paragraphs that are direct children of list items
• Works with: Bullet lists, ordered lists, nested lists, and list items with multiple paragraphs

Implementation Details

The solution tracks parent node context during rendering to determine when a paragraph is inside a list item. By default, paragraphs inside list items are rendered without <p> tags. Users can enable wrapping by calling setWrapParagraphsInListItems(true).

Paragraphs outside of lists continue to render with <p> tags as expected, ensuring that only list items are affected by this option.

Testing

• Added comprehensive test suite (ListTest.php) with 7 test methods covering:
  • Default behavior (no paragraph wrapping)
  • Bullet and ordered lists with wrapping enabled
  • Paragraphs outside lists not being affected
  • Nested lists
  • List items with multiple paragraphs
  • Getter/setter functionality
• All existing tests updated to reflect new default behavior
• Added UPGRADE.md documenting the breaking change and upgrade path from 1.x to 2.x

Fixes the issue where list styling was difficult due to unwanted paragraph tags in list items.

Original prompt

it seems that if you have a list with text, then the list li has a p, which is bad for styling. Check if there is an option to disable this behavior to have the expect result which is

huhu

here is an example output which was generated and is wrong:

• huhu

• hahaha

• hihi

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[nadar]

@copilot

• we need to enable this new behavior by default
• therefore rename the method/property, as skip is then not appropritae
• adjust the existing tests if needed due to this change
• add a changelog.md because its bc break and users need to know how to restore the original behavior

[Copilot]

@copilot

• we need to enable this new behavior by default
  ...

Done in commit 55faebc:

• Changed default behavior to NOT wrap list items in paragraphs (cleaner HTML by default)
• Renamed property/methods from skipParagraphsInListItems to wrapParagraphsInListItems (inverted logic)
• Updated all tests to reflect new default behavior
• Added CHANGELOG.md with migration guide for users who need the old behavior

Users can restore previous behavior with:

$parser->setWrapParagraphsInListItems(true);

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (af83441) to head (c8485ff).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@             Coverage Diff             @@
##                main        #4   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
- Complexity        29        34    +5     
===========================================
  Files              3         3           
  Lines             92       104   +12     
===========================================
+ Hits              92       104   +12     

Flag	Coverage Δ
php-8.1	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nadar]

@copilot rename the changelog.md to upgrade.md and it would be changes from 1.x to 2.x

[Copilot]

@copilot rename the changelog.md to upgrade.md and it would be changes from 1.x to 2.x

Done in commit c8485ff. Renamed CHANGELOG.md to UPGRADE.md and updated content to reflect the upgrade path from version 1.x to 2.x.