Story 2386: Library Page Integration

[julhoang]

Issue: #2386 , #2409

Summary & Context

Ships interactive filter, fuzzy token search (Fuse.js), sort, and empty state designs on the V3 Libraries Page. Adds a new cpp_standard_maximum model field so the C++ version filter can enforce a min/max range.

Filter state lives in an Alpine component, syncs to the URL, and operates on a compact dataset embedded once per page load — no per-keystroke server requests.

• Figma link:
  1. Empty State Designs
  2. New Filter Designs with Cancel Buttons
• Link to page: http://localhost:8000/libraries/latest/list/

Changes

Library page filtering

New UI (_library_filter.html, library_page.html)

• Add clear (X) button to filter controls
• "Most Popular" sort ordering by Tier (Flagship → Core → Deprecated → Legacy)
• Clear All button that only renders when filters are active; resets all fields except View
• Empty state (_library_empty_state.html) with light/dark illustration; distinguishes "no search match" from "no filter match"
• <noscript> fallback hides JS-dependent controls and force-shows x-cloak'd sections so the page still renders

State & wiring

• Inline libraryFilter() Alpine component owns state; syncUrl() hydrates from and writes back ?grading=…&min_cpp=…&max_cpp=…&category=…&q=…&sort=…
• LibraryListBase.get_v3_context_data centralizes filter fields, defaults, the dataset payload, search query, and Clear All URL
• Grading filter only enumerates tiers actually present in the queryset

V3 field include extensions

• _field_dropdown.html — deselectable clear button, field-disabled-values listener (powers min ≤ max C++), field-set rebroadcast, dropdown--has-value accent
• _field_combo_multi.html — per-tag and clear-all buttons, clear-all-filters listener, MutationObserver-friendly hidden inputs
• _field_text.html (used for Search bar) — dispatch_field_change with 150 ms debounce

Fuzzy search (Fuse.js)

• Vendored [email protected] bundled via esbuild (frontend/fuse-entry.js → static/js/v3/fuse.min.js) with yarn build:fuse
• Loaded with defer plus a DOMContentLoaded fallback in init(); if ?q= is in the URL when the late build completes, apply() re-runs so deep links work
• Hero search → 150 ms debounced field-change → query state → runSearch() → fuse.search(q), results keyed by slug
• Score-based sort overrides the default Sort dropdown only when there's an active query; an explicit user sort always wins
• Index built once from {{ library_dataset|json_script:"library-data" }} (slug, name, description, categories, authors, cpp_min/max, tier)

Fuse options

• useTokenSearch: true — multi-word queries match regardless of token order
• ignoreLocation: true — no positional penalty
• threshold: 0.3 — moderate fuzziness (0 = exact, 1 = match anything)
• minMatchCharLength: 2 — drop single-character matches
• includeScore: true — per-result score for relevance ordering
• Weighted keys: name (3) > category_names (1.5) > author_names (1) = description (1)

Max C++ version support

Model & import

• New LibraryVersion.cpp_standard_maximum field (nullable, choices=CPP_STANDARDS) + migration 0040_libraryversion_cpp_standard_maximum
• parse_libraries_json (core/githubhelper.py) reads cxxstd_max; versions/tasks.py assigns it on import, mirroring the existing cxxstd flow
• get_cpp_standard_maximum_display() paralleling the minimum getter (with unit test)
• ❗️ C++23 added to accepted versions; refreshed broken upstream docs link (old broken link here -> new link here)

Filter behavior

• Two dropdowns (Min. C++ Version, Max. C++ Version); both values in the dataset as cpp_min / cpp_max
• Min ≤ max enforced client-side: changing either dispatches field-disabled-values to the other; invalid pairs from URL params auto-correct on load
• Predicate treats each library's [cpp_min … cpp_max] as a range and passes if it overlaps the selected window (e.g. a C++14–20 library matches a Min=C++17 selection)

Risks & Considerations

• Sort is intentionally client-side. Non-JS clients see only the server's alphabetical order (ordering = "library__name" on LibraryListBase).
• Progressive enhancement scope. With JS off, only the View dropdown and the rendered list/grid remain; the search bar, Clear All, and non-View filters are hidden. Crawlers still index the full server-rendered list.
• Fuse.js load ordering. Loaded with defer; init() builds the index immediately if available, otherwise retries on DOMContentLoaded. A ?q= in the URL triggers a re-apply after the late build so deep links still work.
• • Migration safety. 0040 adds a nullable cpp_standard_maximum field — safe forward and reversible. Existing libraries without cxxstd_max in the JSON simply read None and display nothing for the max bound.
• The Saturday 8:03 PM release_tasks Celery chain (also triggerable from Django Admin → "Update Libraries", and on every new release/beta import) reads each library's meta/libraries.json via parse_libraries_json and writes cpp_standard_maximum to the matching LibraryVersion row in import_library_versions. The parser uses libraries_json.get("cxxstd_max") so the field is read opportunistically — if upstream adds cxxstd_max to a library's JSON, it flows in on the next run with no code change; if absent, the field stays None. In the meantime the value is editable directly on the LibraryVersion change form in Django Admin.

Screenshots

Desktop	Mobile	No-JS Version

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
• Accessibility checked (keyboard navigation, etc.)
• Ensure design tokens are used for colors, spacing, typography, etc. – No hardcoded values
• Test without JavaScript (if applicable)
• No console errors or warnings

[julioest]

🚀 Great work on this! Pre-approving, with one inline comment to address before merge.

[jlchilders11]

Looks good to me, thanks for all of the work!

[herzog0]

Heya! Amazing work!!
I just have one note about the min/max logic, which I think should be discussed with Rob.

Pre-approving though 🚢