chore: code clean up, add some documentation

Author: julhoang

libraries/views.py

@@ -204,6 +204,9 @@ def get_v3_context_data(self, queryset=None, **kwargs):
                 "placeholder": "Search",
                 "deselectable": True,
             },
+            # Sort is applied client-side via libraryFilter.sortItems(); no
+            # queryset.order_by() here. The default alphabetical order comes
+            # from the view's `ordering = "library__name"`.
             {
                 "type": "dropdown",
                 "name": "sort",

static/css/v3/forms.css

@@ -314,7 +314,7 @@
   border-color: var(--color-stroke-weak);
   border-bottom-left-radius: 0;
   border-bottom-right-radius: 0;
-  border-bottom-color: var(--color-stroke-weak, #0508161A);
+  border-bottom-color: var(--color-stroke-weak);
 }
 
 .dropdown--has-value .dropdown__trigger,

static/css/v3/library-page.css

@@ -111,7 +111,7 @@ html.dark .library-page-hero .hero-image-dark {
     align-items: center;
 }
 
-.library-page_list-header-justify {
+.library-page__list-header-justify {
     justify-self: center;
     padding-left: calc(16px + var(--space-large));
 }

templates/v3/includes/_field_combo_multi.html

@@ -19,7 +19,7 @@
 {% if selected_values %}
   <script type="application/json" id="field-{{ name }}-selected">{{ selected_values|to_json }}</script>
 {% endif %}
-<div class="field{% if error %} field--error{% endif %}{% if extra_class %} {{ extra_class }}{% endif %}"
+<div class="field {% if error %}field--error{% endif %} {% if extra_class %}{{ extra_class }}{% endif %}"
      @clear-all-filters.window="clearAll()"
   {# djlint:off #}
      x-data="{
@@ -82,7 +82,7 @@
           x-show="!jsReady"
           :disabled="jsReady">
     {% for value, label in options %}
-      <option value="{{ value }}"{% if value in selected_values %} selected{% endif %}>{{ label }}</option>
+      <option value="{{ value }}" {% if value in selected_values %}selected{% endif %}>{{ label }}</option>
     {% endfor %}
   </select>
   <div class="dropdown dropdown--combo" :class="{ 'dropdown--open': open{% if deselectable %}, 'dropdown--has-value': selectedValues.length > 0{% endif %} }" x-cloak>
@@ -129,7 +129,6 @@
               class="dropdown__clear-btn"
               @click.stop="clearAll()"
               x-show="selectedValues.length > 0"
-              x-cloak
               aria-label="Clear all selections"
               tabindex="-1">
         {% include "includes/icon.html" with icon_name="close" icon_class="dropdown__clear-icon" %}

templates/v3/includes/_field_dropdown.html

@@ -17,7 +17,7 @@
   Usage:
     {% include "v3/includes/_field_dropdown.html" with name="country" label="Country" options=country_options placeholder="Select a country" %}
 {% endcomment %}
-<div class="field{% if error %} field--error{% endif %}{% if extra_class %} {{ extra_class }}{% endif %}"
+<div class="field {% if error %}field--error{% endif %} {% if extra_class %}{{ extra_class }}{% endif %}"
      {% if alpine_error %}:class="{ 'field--error': {{ alpine_error }} }"{% endif %}
      {% if not exclude_from_clear %}@clear-all-filters.window="clear()"{% endif %}
      @field-disabled-values.window="if ($event.detail.name === '{{ name }}') disabledValues = $event.detail.values"
@@ -73,7 +73,7 @@
           @change="$dispatch('field-change', { name: '{{ name }}', value: $event.target.value, label: $event.target.options[$event.target.selectedIndex].text })">
     {% if placeholder %}<option value="">{{ placeholder }}</option>{% endif %}
     {% for value, label in options %}
-      <option value="{{ value }}"{% if value == selected %} selected{% endif %}>{{ label }}</option>
+      <option value="{{ value }}" {% if value == selected %}selected{% endif %}>{{ label }}</option>
     {% endfor %}
   </select>
   <div class="dropdown" :class="{ 'dropdown--open': open{% if deselectable %}, 'dropdown--has-value': selected && selected !== defaultValue{% endif %} }" x-cloak>
@@ -153,7 +153,7 @@
   <p class="field__error" role="alert" aria-live="polite" x-show="false">{{ error }}</p>
   {% endif %}
   {% if help_text %}
-  <p class="field__help" id="field-{{ name }}-help" x-show="!{{ alpine_error }}"{% if error %} style="display:none"{% endif %}>{{ help_text }}</p>
+  <p class="field__help" id="field-{{ name }}-help" x-show="!{{ alpine_error }}" {% if error %}style="display:none"{% endif %}>{{ help_text }}</p>
   {% endif %}
   {% else %}
   {% if error %}

templates/v3/includes/_field_text.html

@@ -40,7 +40,7 @@
     Search field (no error handling):
     {% include "v3/includes/_field_text.html" with name="q" placeholder="Search..." submit_icon="arrow-right" submit_label="Search" %}
 {% endcomment %}
-<div class="field{% if error %} field--error{% endif %}{% if extra_class %} {{ extra_class }}{% endif %}"
+<div class="field {% if error %}field--error{% endif %} {% if extra_class %}{{ extra_class }}{% endif %}"
   {# djlint:off #}
     {% if validate_type == "email" %}
     data-validate
@@ -59,7 +59,7 @@
     {% elif alpine_error %}:class="{ 'field--error': {{ alpine_error }} }"{% endif %}>
   {# djlint:on #}
   {% if label %}<label class="field__label" for="field-{{ name }}">{{ label }}</label>{% endif %}
-  <div class="field__control{% if disabled %} field__control--disabled{% endif %}"
+  <div class="field__control {% if disabled %}field__control--disabled{% endif %}"
        {% if submit_icon %}x-data="{ q: '{{ value|default:''|escapejs }}' }"{% endif %}>
     {% if icon_left %}
       <span class="field__icon" aria-hidden="true">
@@ -82,7 +82,7 @@
            {% elif help_text %}
            aria-describedby="field-{{ name }}-help"
            {% endif %}
-           {% if validate_type == "email" %}x-model="value" @blur="touched = true"{% elif submit_icon %}x-model="q"{% if dispatch_field_change %} @input.debounce.150ms="$dispatch('field-change', { name: '{{ name }}', value: q })"{% endif %}{% endif %}>
+           {% if validate_type == "email" %}x-model="value" @blur="touched = true"{% elif submit_icon %}x-model="q" {% if dispatch_field_change %}@input.debounce.150ms="$dispatch('field-change', { name: '{{ name }}', value: q })"{% endif %}{% endif %}>
     {% if submit_icon %}
       <button type="submit"
               class="field__submit"

templates/v3/includes/_library_item.html

@@ -20,7 +20,7 @@
   Usage (card):
     {% include "v3/includes/_library_item.html" with variant="card" library_name="Boost.Asio" description="Portable networking and low-level I/O." categories=cats cpp_version="C++ 11" author=author doc_url="/libs/asio/doc/" %}
 {% endcomment %}
-{% if variant == "list" %}<li class="library-item library-item--list"{% if library_slug %} data-slug="{{ library_slug }}"{% endif %} {{ extra_attrs|safe }}>{% else %}<div class="library-item library-item--card"{% if library_slug %} data-slug="{{ library_slug }}"{% endif %} {{ extra_attrs|safe }}>{% endif %}
+{% if variant == "list" %}<li class="library-item library-item--list" {% if library_slug %}data-slug="{{ library_slug }}"{% endif %} {{ extra_attrs|safe }}>{% else %}<div class="library-item library-item--card" {% if library_slug %}data-slug="{{ library_slug }}"{% endif %} {{ extra_attrs|safe }}>{% endif %}
 
   <div class="library-item__header">
     {% if library_url %}

templates/v3/library_page.html

@@ -37,9 +37,27 @@
   {{ library_dataset|json_script:"library-data" }}
   {{ library_filter_defaults|json_script:"library-filter-defaults" }}
   <script>
-    /* Defined inline so the factory is on window before Alpine evaluates x-data
+    /* libraryFilter() — page-scoped Alpine component that owns search/filter/sort.
+       All three pipelines are client-side; the server returns the full dataset
+       for the selected Boost version, embedded as the `library-data` script tag.
+
+       State:
+         dataset, defaults      — loaded once from script tags at init().
+         grading, minCpp,       — current filter selections, hydrated from URL
+         maxCpp, categories,      params and mirrored back via syncUrl().
+         query, sort
+         searchHits/Scores      — Fuse output keyed by slug (null when no query).
+         visibleCount           — drives empty-state visibility from toggleItems().
+
+       Wiring: child field components dispatch `field-change` events; the parent
+       listens, updates state, calls apply() which runs search → URL sync →
+       toggle → sort → empty-state in order.
+
+       Defined inline so the factory is on window before Alpine evaluates x-data
        on this page — defer-script load ordering can otherwise race Alpine.start. */
     window.libraryFilter = function () {
+      // Keep in sync with LibraryVersion.CPP_STANDARD_DISPLAY_NAMES — used for
+      // min/max C++ range ranking and the disabled-option constraints.
       const CPP_STANDARDS = [
         { key: '98', year: 1998, label: 'C++98' },
         { key: '03', year: 2003, label: 'C++03' },
@@ -112,6 +130,8 @@
           this.query = params.get('q') || '';
           this.sort = params.get('sort') || this.defaults.sort;
 
+          // Child fields dispatch `field-change` with {name, value}; route to
+          // the matching state slot, enforce min/max C++ ordering, then apply().
           this.$el.addEventListener('field-change', (event) => {
             const { name, value } = event.detail;
             if (name === 'grading') this.grading = value || 'all';
@@ -277,8 +297,9 @@
           items.forEach((el) => {
             const data = bySlug.get(el.dataset.slug);
             const show = data ? this.matches(data) : true;
-            // Inline style beats the `[hidden]` attribute, which is overridden
-            // by .library-item--list / --card's `display: grid`.
+            // Inline style beats `[hidden]`. The item containers use
+            // `display: grid` (with subgrid on .library-item--list), which
+            // overrides the default `[hidden] { display: none }` rule.
             el.style.display = show ? '' : 'none';
             if (show) visible += 1;
           });
@@ -359,6 +380,7 @@
       };
     };
   </script>
+
   <div class="library-page__container" x-data="libraryFilter()">
     <section class="library-page-hero" aria-label="Hero">
           <h1 class="hero-title">Find a battle-tested library for the problem you're solving right now.</h1>
@@ -382,7 +404,7 @@ <h1 class="hero-title">Find a battle-tested library for the problem you're solvi
           <div class="library-page__list-header-flex"><span class="library-page__list-header-text">Description</span>{% include "includes/icon.html" with icon_name="chevron-down" icon_size=16 %}</div>
           <div class="library-page__list-header-flex"><span class="library-page__list-header-text">Category</span>{% include "includes/icon.html" with icon_name="chevron-down" icon_size=16 %}</div>
           <div class="library-page__list-header-flex"><span class="library-page__list-header-text">Author</span>{% include "includes/icon.html" with icon_name="chevron-down" icon_size=16 %}</div>
-          <div class="library-page__list-header-flex library-page_list-header-justify"><span class="library-page__list-header-text">Version</span>{% include "includes/icon.html" with icon_name="chevron-down" icon_size=16 %}</div>
+          <div class="library-page__list-header-flex library-page__list-header-justify"><span class="library-page__list-header-text">Version</span>{% include "includes/icon.html" with icon_name="chevron-down" icon_size=16 %}</div>
           <div></div>
         </li>
         {% for item in object_list %}
@@ -420,7 +442,3 @@ <h2 class="library-page__category-header">{{ result.category }} {% if result.ico
     {% endif %}
   </div>
 {% endblock %}
-
-{% block footer_js %}
-  {{ block.super }}
-{% endblock %}