Skip to content

✨ Add an accordion component#291

Open
chrisjsewell wants to merge 3 commits into
mainfrom
brief/17-accordion
Open

✨ Add an accordion component#291
chrisjsewell wants to merge 3 commits into
mainfrom
brief/17-accordion

Conversation

@chrisjsewell

@chrisjsewell chrisjsewell commented Jul 16, 2026

Copy link
Copy Markdown
Member

Adds an accordion directive: a group of dropdowns where opening one closes the others — with zero JavaScript. The directive stamps a shared, deterministic name attribute onto its direct child dropdowns' <details> elements, and the browser's native exclusive-open behaviour does the rest.

.. accordion::

   .. dropdown:: First item

      Content

   .. dropdown:: Second item
      :open:

      Content

Behaviour

  • Only direct child dropdowns join the group — a dropdown nested inside an item's content stays independent (tested).
  • At most one :open: item: a second is stripped from the output with a suppressible design.accordion warning.
  • Non-dropdown children warn (design.accordion) and are dropped, except inert hyperlink targets, which are kept so :ref: anchors keep working.
  • :flush: renders the group edge-to-edge; custom directives can inherit accordion via sd_custom_directives (tested).
  • Group names are sd-accordion-<slug>-<digest>-<serial> — the digest of the raw docname guards against slug collisions (a/b vs a-b) coupling unrelated groups in singlehtml/concatenated builds, which review caught with a browser-verified reproduction and is now locked in by a dedicated singlehtml test.

Browser support

<details name> is Baseline Newly Available (Chrome/Edge 120+, Firefox 130+, Safari 17.2+) — a documented per-feature exception to the support policy: older browsers simply ignore the attribute and render ordinary independently-collapsible dropdowns. Nothing breaks, no JS fallback involved.

Verification

  • Native exclusivity verified in real Chromium (Playwright): click and keyboard (Enter/Space) toggling closes siblings; nested dropdowns unaffected
  • Plain dropdowns are byte-identical to main (the dropdown.py visitor change is a strict no-op without the attribute)
  • Full test/lint/type matrix green; docs -nW; the CSS artifact regenerated through the generator pipeline (style/accordion.css registered in ASSEMBLY after dropdown.css)

An `accordion` directive groups `dropdown`s so that opening one item
collapses the others, using the native, JavaScript-free `<details name>`
attribute. Only direct child dropdowns join the group (nested dropdowns
stay independent), at most one item may start `:open:`, and a `:flush:`
flag provides an edge-to-edge variant.

`<details name>` is Baseline Newly Available; it degrades gracefully
(older browsers keep each item independently collapsible), as documented
on the new accordions page.
`nodes.make_id` is lossy (`a/b`, `a-b`, `a.b` all fold to `a-b`) and the
serial counter is per-document, so accordions in docnames sharing a slug
produced identical `<details name>` values. In a `singlehtml` build these
land on one page and their exclusive-open groups coupled together.

Append a short SHA-1 digest of the raw docname to the group name so
colliding slugs stay distinct; add a singlehtml regression test and make
the existing assertions structural rather than digest-hardcoded.
@codecov

codecov Bot commented Jul 16, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 92.85714% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.63%. Comparing base (4f66f32) to head (b98b166).

Files with missing lines Patch % Lines
sphinx_design/accordion.py 91.48% 4 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #291      +/-   ##
==========================================
- Coverage   92.63%   92.63%   -0.01%     
==========================================
  Files          13       14       +1     
  Lines        1371     1425      +54     
==========================================
+ Hits         1270     1320      +50     
- Misses        101      105       +4     
Flag Coverage Δ
pytests 92.63% <92.85%> (-0.01%) ⬇️

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

☔ 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.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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