fix(docs) Simplify documentation for HTML element enums and enhance clarity on contract implementations.#11
Conversation
…larity on contract implementations.
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdds Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/MetadataBlock.php (1)
8-14:⚠️ Potential issue | 🟡 MinorCopyright year is inconsistent with the other files modified in this PR.
src/MetadataBlock.phpcarries@copyright Copyright (C) 2026whilesrc/Lists.php,src/Block.php, andsrc/VoidInterface.php(all touched in the same PR in 2026) still state 2025. If this PR reflects work done in 2026, the copyright year should be updated consistently across all modified files.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/MetadataBlock.php` around lines 8 - 14, The copyright year in the file header for MetadataBlock.php is inconsistent (shows 2026) with other modified files (Lists.php, Block.php, VoidInterface.php) which use 2025; update the header in MetadataBlock.php to match the project's chosen year (change the Copyright (C) 2026 to Copyright (C) 2025) so all files modified in this PR are consistent—locate the header comment at the top of MetadataBlock.php around the MetadataBlock class/block enum declaration and edit the year accordingly.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (12)
CHANGELOG.mdsrc/Block.phpsrc/BlockInterface.phpsrc/Inline.phpsrc/InlineInterface.phpsrc/Lists.phpsrc/MetadataBlock.phpsrc/MetadataVoid.phpsrc/Root.phpsrc/Table.phpsrc/VoidInterface.phpsrc/Voids.php
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: linter / Super Linter
- GitHub Check: linter / Super Linter
🔇 Additional comments (11)
src/InlineInterface.php (1)
9-16: LGTM!The simplified docblock is concise and accurately describes the interface contract.
src/BlockInterface.php (1)
9-16: LGTM!Consistent with the simplified docblock pattern applied across interfaces in this PR.
src/Table.php (1)
7-14: LGTM!Docblock is clear and consistent with the pattern used across other enum files.
src/MetadataVoid.php (1)
7-14: LGTM!Docblock is concise and consistent with the broader documentation pattern in this PR.
src/Root.php (1)
7-14: LGTM!Consistent docblock simplification. No concerns.
src/Voids.php (1)
7-14: LGTM!Docblock is clear and follows the same pattern as other enum files.
src/Inline.php (1)
7-14: LGTM!Consistent and clear docblock simplification.
CHANGELOG.md (1)
5-5: Review comment is incorrect — no enum cases were removed.The PR is a documentation fix ("fix(docs)") that simplifies and clarifies the Block enum documentation, not a breaking change. Block.php never contained
H1–H6enum cases (heading elements are semantic content, not block-level elements). The changelog entry correctly labels this as a "Bug" fix for documentation improvement. No version bump or breaking change declarations are needed.Likely an incorrect or invalid review comment.
src/Lists.php (1)
8-8: LGTM.The docblock simplification is accurate and clearly describes the enum's nature and implemented contract.
src/VoidInterface.php (1)
10-10: LGTM.The simplified docblock accurately describes the interface's purpose and its relationship to
BackedEnum. The added "(self-closing)" parenthetical improves clarity over the prior description.src/Block.php (1)
1-300: No H1–H6 removal in this PR — review comment is based on incorrect assumptions.The reviewed change (version 0.3.1) is solely a documentation simplification of HTML element enums. The codebase contains no H1–H6 cases in the
Blockenum, no separateHeadingenum, and no references to H1–H6 anywhere. The changelog for this PR makes no mention of H1–H6 removal, breaking changes, or enum refactoring. H1–H6 are either not part of this library's scope or were removed in an earlier version unrelated to this PR.Likely an incorrect or invalid review comment.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/Block.php`:
- Around line 141-148: The docblock for the enum case FORM incorrectly lists
"form-associated" — update the documentation for the case FORM = 'form' to
remove "form-associated" and state that the <form> element is categorized as
flow content and palpable content only; edit the block comment above the case
FORM constant in Block.php to reflect this corrected classification and keep the
MDN link intact for reference.
- Around line 188-193: Update the PHPDoc for the LEGEND enum case in Block.php:
remove the incorrect phrase "Categorized as flow, form-associated, and palpable
content" and replace it with a concise note stating that the <legend> element
has no standard content categories (e.g., "Elements without a category" per
MDN). Ensure the comment remains near the case LEGEND = 'legend' so it documents
that enum member accurately.
- Around line 267-290: The Block enum incorrectly contains SELECT and TEXT_AREA
cases (symbols SELECT and TEXT_AREA) which are phrasing/form-associated
elements; move these two enum members out of the Block enum and add them to the
Inline enum (keeping or copying their docblocks/links), remove them from Block,
and update any references/usages/tests that expect Block::SELECT or
Block::TEXT_AREA to instead use Inline::SELECT and Inline::TEXT_AREA so callers
and type checks reflect the new placement.
---
Outside diff comments:
In `@src/MetadataBlock.php`:
- Around line 8-14: The copyright year in the file header for MetadataBlock.php
is inconsistent (shows 2026) with other modified files (Lists.php, Block.php,
VoidInterface.php) which use 2025; update the header in MetadataBlock.php to
match the project's chosen year (change the Copyright (C) 2026 to Copyright (C)
2025) so all files modified in this PR are consistent—locate the header comment
at the top of MetadataBlock.php around the MetadataBlock class/block enum
declaration and edit the year accordingly.
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/Block.php (1)
15-300:⚠️ Potential issue | 🟠 MajorH1–H6 removal breaks backward compatibility and contradicts documentation.
The Block enum no longer contains H1–H6 cases, but the README.md file includes a code example that filters Block cases by the heading pattern (
str_starts_with($tag->name, 'H')) and explicitly shows the output ash1throughh6. This example is now broken.Two confirmed issues:
BC break: Removing
Block::H1throughBlock::H6will cause fatal "Undefined enum case" errors in any code—application, tests, or downstream packages—that references these cases. The PR description marks "Breaks BC: ❌", which is incorrect.Inconsistent documentation: The README.md code example (under "Filtering and iterating tags") no longer works with the current Block enum and should be updated to remove the heading filter example or the cases should be restored.
Per the library's own classification rule (Block = elements with distinct opening/closing tags), H1–H6 clearly qualify alongside other block-level elements already in the enum.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/Block.php` around lines 15 - 300, The Block enum removed the H1–H6 cases, breaking backwards compatibility and invalidating the README example that filters tags by heading names; restore the enum cases Block::H1 through Block::H6 (values 'h1'..'h6') inside the Block enum definition so existing references and the README example continue to work, and update the PR metadata to mark "Breaks BC" as ❌ if it currently states otherwise; alternatively, if removal was intentional, update README's "Filtering and iterating tags" example to remove the heading filter and add a migration note, but the recommended fix is to re-add the H1–H6 enum cases to Block to preserve BC.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
src/Block.php
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: terabytesoftw
Repo: ui-awesome/html-interop PR: 11
File: src/Block.php:267-290
Timestamp: 2026-02-21T14:17:54.250Z
Learning: In the ui-awesome/html-interop library, the Block enum classification is based on elements that have begin() and end() methods (separate opening and closing tags), while the Inline enum is for elements rendered on the same line (like <span></span>). This is not based on HTML's standard content categories (block-level vs phrasing content), but rather on the library's API pattern for rendering elements. Elements like <select> and <textarea> belong in Block because they use begin/end methods, even though they are technically phrasing content in HTML specifications.
📚 Learning: 2026-02-21T14:17:54.250Z
Learnt from: terabytesoftw
Repo: ui-awesome/html-interop PR: 11
File: src/Block.php:267-290
Timestamp: 2026-02-21T14:17:54.250Z
Learning: In code reviews for ui-awesome/html-interop, classify Block vs Inline based on the library's API pattern, not HTML's block/phrasing categories. Specifically: - Block enum should include elements that use distinct begin() and end() methods (separate opening and closing tags). - Inline enum covers elements rendered on the same line. Do not rely on HTML content-model assumptions. For example, elements like <select> and <textarea> should be categorized as Block because they use begin/end methods, even though they are phrasing content in HTML. Apply this rule consistently to files that define or modify Block/Inline classifications in the codebase.
Applied to files:
src/Block.php
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: linter / Super Linter
- GitHub Check: linter / Super Linter
🔇 Additional comments (2)
src/Block.php (2)
188-193: LGTM — LEGEND docblock correctly updated.Replacing the incorrect content-category annotation with "Permitted as the first child of a
{@seeself::FIELDSET}element" accurately reflects MDN's description and resolves the previously flagged issue.
267-290: LGTM —SELECTandTEXT_AREAcorrectly placed inBlockper the library's begin/end API convention.Based on learnings, elements that use distinct
begin()/end()rendering methods belong inBlockregardless of their HTML content category, and both<select>and<textarea>satisfy that criterion.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/Block.php`:
- Line 110: Update the docblock line that currently reads "Categorized as flow,
and palpable content." to remove the spurious comma so it matches other two-item
lines (e.g., ADDRESS, BLOCKQUOTE, FIGURE); locate the line in src/Block.php (the
Block class docblock) and change it to "Categorized as flow and palpable
content." to maintain consistency.
- Around line 8-10: Update the top-level docblock for the Block enum (the backed
string enum implementing BlockInterface) to reflect that it lists elements
treated by the library with distinct begin()/end() rendering calls rather than
literal HTML "block-level content"; remove or replace the existing MDN
"Block-level content" `@link` and change the description text to state the enum's
purpose (elements rendered via separate begin()/end() methods), optionally
linking to an internal docs page or a more appropriate spec that matches this
membership rule.
---
Outside diff comments:
In `@src/Block.php`:
- Around line 15-300: The Block enum removed the H1–H6 cases, breaking backwards
compatibility and invalidating the README example that filters tags by heading
names; restore the enum cases Block::H1 through Block::H6 (values 'h1'..'h6')
inside the Block enum definition so existing references and the README example
continue to work, and update the PR metadata to mark "Breaks BC" as ❌ if it
currently states otherwise; alternatively, if removal was intentional, update
README's "Filtering and iterating tags" example to remove the heading filter and
add a migration note, but the recommended fix is to re-add the H1–H6 enum cases
to Block to preserve BC.
---
Duplicate comments:
In `@src/Block.php`:
- Around line 141-148: The PHPDoc for the enum case FORM incorrectly lists
"form-associated" — update the docblock for the case FORM in src/Block.php to
remove "form-associated" and state only "flow" and "palpable content" (i.e.,
change the descriptive line above case FORM = 'form' to reflect that <form> is
the form owner and belongs only to flow and palpable content per the HTML
standard); ensure the `@link` and other lines remain intact but adjust the short
description to remove the incorrect "form-associated" term.
There was a problem hiding this comment.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
src/Block.php
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2026-02-21T14:17:54.250Z
Learnt from: terabytesoftw
Repo: ui-awesome/html-interop PR: 11
File: src/Block.php:267-290
Timestamp: 2026-02-21T14:17:54.250Z
Learning: In code reviews for ui-awesome/html-interop, classify Block vs Inline based on the library's API pattern, not HTML's block/phrasing categories. Specifically: - Block enum should include elements that use distinct begin() and end() methods (separate opening and closing tags). - Inline enum covers elements rendered on the same line. Do not rely on HTML content-model assumptions. For example, elements like <select> and <textarea> should be categorized as Block because they use begin/end methods, even though they are phrasing content in HTML. Apply this rule consistently to files that define or modify Block/Inline classifications in the codebase.
Applied to files:
src/Block.php
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: linter / Super Linter
- GitHub Check: linter / Super Linter
🔇 Additional comments (3)
src/Block.php (3)
240-247: LGTM —<legend>docblock correctly updated.The note "Permitted as the first child of a
{@seeself::FIELDSET}element." is accurate per MDN and addresses the prior review finding.
321-328: LGTM —SELECTcorrectly added toBlock.The docblock categorization is accurate per MDN, and placement in
Block(rather thanInline) is intentional per the library'sbegin()/end()rendering API pattern. Based on learnings,<select>belongs here because it uses separate opening and closing tag rendering calls.
337-344: LGTM —TEXT_AREAcorrectly added toBlock.Docblock categorization matches MDN, and
begin()/end()API semantics confirm placement inBlock. Based on learnings,<textarea>belongs here for the same reason as<select>.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@src/Block.php`:
- Line 110: Remove the spurious comma in the FIELDSET docblock: find the
docblock that contains the phrase "Categorized as flow, and palpable content."
(the FIELDSET documentation) and edit it to read "Categorized as flow and
palpable content." so it matches the comma-less two-item phrasing used by other
entries like ADDRESS, BLOCKQUOTE, FIGURE, and FOOTER.
1 participant
Pull Request