Skip to content

Document the slot element/attribute name clash - #339

Open
maragubot wants to merge 2 commits into
maragudk:mainfrom
maragubot:garden/document-slot-name-clash
Open

Document the slot element/attribute name clash#339
maragubot wants to merge 2 commits into
maragudk:mainfrom
maragubot:garden/document-slot-name-clash

Conversation

@maragubot

@maragubot maragubot commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

What was found

Three docs describe the element/attribute name clashes: the README's "What's up with the specially named elements and attributes?" section, the "Name Conflicts" section in LLMs.md, and the "Attribute vs Element Disambiguation" bullets in AGENTS.md (symlinked as CLAUDE.md). All three covered six names — cite, data, form, label, style, title — and omitted slot.

html.SlotEl and html.SlotAttr both exist (added in #235) and neither is deprecated, so slot is a seventh clash. It's also the one that breaks the rule the docs state: for the other six, one form gets the plain name and the other gets a suffix, so a reader following that rule reaches for Slot and finds nothing.

I intersected every name passed to g.El(...) with every name passed to g.Attr(...) in the html package; the overlap is exactly the seven names now listed, so nothing else is missing.

What was fixed

Added slot to all three docs. In the README and LLMs.md it joins the list in alphabetical order, with the exception flagged where a reader meets it rather than in a footnote below the list. In AGENTS.md it's one bullet alongside the existing convention rules.

The wording deliberately states only what the API looks like today and asserts no rationale. An earlier draft of this branch claimed both forms keep a suffix because neither is clearly more common; self-review found that was invented. #235 shows the suffixing was a deferral — "not add the non-suffixed version for now" — not a judgement about usage, so putting that reasoning in the README's first-person voice would have misattributed it.

Review notes

AGENTS.md was initially left out of this PR to avoid colliding with #338, which is open against the same file. That turned out to be unfounded — #338's hunks end around line 34 and these bullets are at 63-67 — so it's included here, where the finding belongs.

One pre-existing issue surfaced during review and is left alone: html.Data(name, v string) is the data-* helper, so the real data attribute (on <object>) has no function at all, and Data() in the LLMs.md list implies a zero-argument signature it doesn't have.

Worth deciding rather than implicitly ratifying: since #235 framed the double suffix as temporary, you may prefer to close the gap by adding a plain Slot instead of documenting the exception.

The name clash lists in the README and LLMs.md covered six names but
omitted `slot`. Both `html.SlotEl` and `html.SlotAttr` exist, and unlike
the other six clashes neither gets the plain name, so a reader following
the documented rule would reach for `Slot` and not find it.
@codecov

codecov Bot commented Jul 29, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (76f04c0) to head (37bf6a6).

Additional details and impacted files
@@            Coverage Diff            @@
##              main      #339   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            6         6           
  Lines          639       639           
=========================================
  Hits           639       639           

☔ View full report in Codecov by Harness.
📢 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.

AGENTS.md states the naming convention without the carve-out, and it's
the file assistants read first, so it was the remaining place likely to
suggest a plain `Slot`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant