Document heading ID CSS-validity deviation from djot spec (jgm/djot#391)#179
Merged
Merged
Conversation
Cross-reference jgm/djot#391, where the spec wording on auto-ID generation is being clarified. djot-php aligns with the proposed direction on remove-vs-replace and Unicode preservation, but deliberately deviates on apostrophes, double quotes, semicolons, and colons (replacing rather than preserving) because heading IDs are consumed by querySelector() and need to be valid CSS identifiers. Add a Spec Alignment section to the existing CSS-Safe Heading IDs reference, and pin the relevant edge cases with a focused regression test so the deliberate behavior is locked in if/when the spec lands.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #179 +/- ##
=========================================
Coverage 93.51% 93.51%
Complexity 3242 3242
=========================================
Files 93 93
Lines 8207 8207
=========================================
Hits 7675 7675
Misses 532 532 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
PhpCollective enables both PSR12.Classes.AnonClassDeclaration.SpaceAfterKeyword
(wants 1 space between 'class' and '(') and Universal.WhiteSpace.AnonClassKeywordSpacing
(wants no space). The two rules contradict each other, so any anonymous class
declaration fails CS regardless of how it is written. Exclude the PSR12 rule so
the Universal sniff wins, unblocking CI on this PR.
PhpCollective code-sniffer now configures Universal.WhiteSpace.AnonClassKeywordSpacing
with spacing=1, matching the existing PSR12.Classes.AnonClassDeclaration.SpaceAfterKeyword
rule. The two rules agree on '1 space between class and (' so the prior exclude is no
longer needed; revert it and apply the actual one-character source fix.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
',",;,:.testNormalizeIdSpecAlignmentEdgeCases()so the behavior is locked in if/when the spec lands.Rationale
The current djot spec says auto-IDs are formed by "removing punctuation (other than
_and-)". In practice djot.js (the reference), djoths (pandoc's engine), and most community implementations — including djot-php — replace mid-word punctuation with-. The cross-implementation comparison on jgm/djot#391 shows the spec is moving toward "replace".djot-php goes one step further:
',",;,:are also replaced with-. These characters are not valid in unescaped CSS identifiers, so preserving them per the proposed spec would force every JS consumer to round-trip throughCSS.escape()before doing aquerySelector('#...')lookup. In practice almost nobody does this, and it silently breaks anchors and HTMX scroll-restoration on headings like# That's all.This PR makes that choice explicit and defensible rather than implicit divergence. No behavior change — only docs + tests.
What changes
docs/reference/enhancements.md: add Heading auto-ID: clarify punctuation handling (remove vs replace) jgm/djot#391 to the Related line; add a Spec Alignment subsection.tests/TestCase/Renderer/HeadingIdTrackerTest.php: newtestNormalizeIdSpecAlignmentEdgeCases()covering the eight cases highlighted by the upstream discussion.