Story #2560: implement the unavailable library page UI

[ycanales]

Issue: #2560

Stacked on #2524 (julia/improve-library-subpage-layout), which added the placeholder this replaces. Retarget to develop once #2524 merges. Trying out the Github stacked layout thing.

Summary & Context

Replaces the inline placeholder on the v3 library subpage with the designed empty state for a library that has no version in the selected Boost release: headline, a sentence naming the library and versions, a "Switch to ..." CTA and the bookshelf illustration.

• Figma link: Unavailable Library page
• Link to components/page: http://localhost:8000/library/1.61.0/beast/

Changes

View (libraries/views.py)

• Add LibraryDetail.get_missing_version_context(), which builds the sentence and the CTA label/URL. Both branch on data, so neither can live in the template: a library with no releases at all drops the "first release was ..." clause and gets no CTA, and the CTA targets the newest release that actually ships the library rather than always "latest".
• get_v3_context_data() now returns early for the missing-version case, so the subpage's contributor, quick-start, dependency and benchmark context is no longer computed for a page that renders none of it.
• Drop the placeholder TODO.

Hero component (templates/v3/includes/_hero_library.html)

• Add optional cta_label / cta_url / cta_icon_name, rendered through the existing _button_hero.html inside .hero__actions. The block collapses when they are absent, so every existing caller is unchanged.

Empty state template (templates/v3/includes/_library_version_unavailable.html, new)

• Wires the hero to the empty-state copy and to the existing empty-library-light/dark.png illustration already shipped for the library-list empty state. No new asset: it is the same artwork as the Figma frame.

Styles (static/css/v3/heros.css)

• New hero--library-unavailable variant: page surface instead of the hero's accent yellow, Figma's 32px rhythm between headline, sentence and CTA, and a bottom-flush illustration.
• The block's fixed height becomes a min-height for this variant only, since the empty state's copy is longer than a library hero's and would otherwise overflow the CTA onto the version alert in the tablet band.
• The illustration ships on an opaque plate (white in the light export, black in the dark one), so it is blended into the surface with multiply / screen. That needs a matching background on .hero__image, because .hero__block opens a stacking context and closes the blending group above the section background.

Tests (libraries/tests/test_views.py)

• Two tests covering the empty-state context and the dropped-library CTA.
• Pin the legacy v2 test_library_detail_missing_version with override_flag("v3", active=False). It was passing only on ambient flag state and flipped to the v3 template whenever the cached waffle flag was warm.

‼️ Risks & Considerations ‼️

• ‼️ The CTA does not always point at "latest". For a library dropped from Boost, "latest" is a dead end that renders this same empty state, so the button targets the library's last release instead and the label changes from "Switch to latest (1.91.0)" to "Switch to 1.86.0". See screenshot 6.
• Rejected: a standalone empty-state template. Reusing _hero_library.html costs three optional variables and keeps the responsive type ladder, the theme-aware image swap and the version alert in one place. A separate template would have duplicated all three and drifted from the other heroes.
• Rejected: building the sentence in the template. It reads as static copy but interpolates three dynamic values and has a conditional clause. VersionAlertMixin.get_version_alert_message sets the precedent for keeping that branching in Python.
• alt="" on the illustration is deliberate. It is decorative here, and the <h1> and paragraph carry the message.
• The version alert renders below the hero block, where the Figma frame puts it above the hero. That is existing behaviour shared by every library hero and is left alone rather than changed for one page.

Peer-Testing Guidelines

Both states are real Boost history, so every URL below works on any environment with the catalogue imported.

1. (Local only.) Check out the branch and apply the migrations that come with Story 2430: Library Subpage Integration #2524. Confirm the v3 waffle flag is active. If the page renders the legacy layout, the cached flag is stale:

   docker compose exec redis redis-cli FLUSHALL
   

2. Default state: release older than the library's first. Boost.Beast first shipped in 1.66.0, so visit /library/1.61.0/beast/. Expect the headline, the sentence naming both versions, a "Switch to latest (1.91.0)" button naming the current release, and the illustration on the page surface (not the yellow hero background). The button should land on /library/latest/beast/.

3. Dropped library. Boost.Compatibility last shipped in 1.86.0, so visit /library/latest/compatibility/. The button should read "Switch to 1.86.0" and link to /library/1.86.0/compatibility/, not back to latest.

4. Responsive and themes. Resize through 1440 / 768 / 375 in both themes. The illustration should have no visible panel edge behind it in either theme, and at 768 the CTA must stay clear of the version alert banner.

5. No regression on a populated subpage. Visit /library/latest/beast/ and confirm the hero still shows the tag row and the Documentation / Source code / Slack / GitHub Issues links, with no CTA button.

More examples, and how to find your own from the site or admin

Extra URLs for step 3, libraries added recently enough that older releases predate them:

URL	Library was added in
/library/1.85.0/decimal/	1.91.0
/library/1.80.0/cobalt/	1.84.0
/library/1.80.0/mysql/	1.82.0

Extra URLs for step 4, libraries dropped from Boost, all visited at latest:

URL	Expected CTA
/library/latest/functionalhash/	Switch to 1.77.0
/library/latest/mathquaternion/	Switch to 1.82.0
/library/latest/signals/	Switch to 1.68.0

To find your own without database access:

• From the site, open a library subpage at latest. The hero carries an "Added in {version}" chip, and picking any older release from the version dropdown lands on the step 3 state.
• From the admin, search a library name in /admin/libraries/libraryversion/. The list shows every release that ships the library, newest first. If the top row is below the current Boost release the library is a step 4 candidate, and that row is the version the CTA should target.

Screenshots

Drag the matching file from claudetmp/pr-2560/ into each cell.

Screenshot	Notes
	Desktop 1440, light. Matches the Figma frame: headline over two lines, sentence, accent CTA, illustration bottom-flush on the page surface.
	Desktop 1440, dark. Dark illustration export, no visible plate behind it.
	Tablet 768. Headline steps to 40px and wraps to three lines; the block grows so the CTA clears the version alert.
	Mobile 375, light. Content stacks, CTA goes full width, illustration drops below.
	Mobile 375, dark.
	Boost.Compatibility at latest: the CTA reads "Switch to 1.86.0", the library's last release, instead of pointing back at latest.

Self-review Checklist

• Tag at least one team member from each team to review this PR
• Link this PR to the related GitHub Project ticket

Frontend

• UI implementation matches Figma design
• Tested in light and dark mode
• Responsive / mobile verified (1440 / 768 / 375)
• Accessibility checked: <h1> carries the message, the CTA is a plain focusable link, the illustration is decorative (alt="")
• Ensure design tokens are used for colors, spacing, typography, etc. No hardcoded values
• Test without JavaScript (the page is static markup)
• No console errors or warnings

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 485cee49-6244-4eba-8360-14fbf2ef4f64

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}