From aed94f1522935efb4a739f77ffb147dee654fca1 Mon Sep 17 00:00:00 2001
From: Mir Bhatia <m.bhatia@openproject.com>
Date: Fri, 12 Jun 2026 12:43:22 +0200
Subject: [PATCH] Update quick filter lookbook docs

---
 .../docs/patterns/10-quick-filters.md.erb     | 19 +++++++++++++++++--
 .../op_primer/quick_filter_preview.rb         |  7 +++++++
 .../select_panel_single_select.html.erb       | 12 ++++++++++++
 3 files changed, 36 insertions(+), 2 deletions(-)
 create mode 100644 lookbook/previews/op_primer/quick_filter_preview/select_panel_single_select.html.erb

diff --git a/lookbook/docs/patterns/10-quick-filters.md.erb b/lookbook/docs/patterns/10-quick-filters.md.erb
index e626973bde5..a3a00a46862 100644
--- a/lookbook/docs/patterns/10-quick-filters.md.erb
+++ b/lookbook/docs/patterns/10-quick-filters.md.erb
@@ -36,9 +36,24 @@ Note: Clicking on buttons in the above preview will break it and redirect to the
 
 ## SelectPanelComponent
 
-A multiselect select panel based quick filter. Select panel items are provided via `with_item` slots.
-Navigation happens when items are checked and the "Apply" button is clicked.
+A select panel based quick filter. Items are provided via `with_item` slots or loaded asynchronously via `src`.
+By default, in multiselect mode, navigation happens when items are checked and the "Apply" button is clicked.
+When the query has a matching active filter, the corresponding items are checked, the show button gets a counter,
+and a "Clear" button is rendered in the panel footer.
 
 <%= embed OpPrimer::QuickFilterPreview, :select_panel_with_active_filter, panels: %i[source] %>
 
 Note: Clicking on buttons in the above preview will break it and redirect to the meetings index page.
+
+### Single select
+
+With `select_variant: :single`, each item navigates immediately on click and there are no footer buttons.
+
+<%= embed OpPrimer::QuickFilterPreview, :select_panel_single_select, panels: %i[source] %>
+
+Note: Clicking on buttons in the above preview will break it and redirect to the meetings index page.
+
+### Async loading
+
+Pass `src` to lazily load the panel items from an endpoint instead of providing them inline.
+The filter must implement `#value_objects`, and `src` cannot be combined with inline items or `select_variant: :single`.
diff --git a/lookbook/previews/op_primer/quick_filter_preview.rb b/lookbook/previews/op_primer/quick_filter_preview.rb
index 239f66a683c..6d246ce3338 100644
--- a/lookbook/previews/op_primer/quick_filter_preview.rb
+++ b/lookbook/previews/op_primer/quick_filter_preview.rb
@@ -30,6 +30,7 @@
 
 module OpPrimer
   # @logical_path OpenProject/Primer
+  # @display min_height 400px
   class QuickFilterPreview < Lookbook::Preview
     def segmented_control
       render_with_template(locals: { query: meeting_query })
@@ -53,6 +54,12 @@ module OpPrimer
       render_with_template(locals: { query: })
     end
 
+    def select_panel_single_select
+      query = meeting_query
+      query.where("time", "=", ["past"])
+      render_with_template(locals: { query: })
+    end
+
     private
 
     def meeting_query
diff --git a/lookbook/previews/op_primer/quick_filter_preview/select_panel_single_select.html.erb b/lookbook/previews/op_primer/quick_filter_preview/select_panel_single_select.html.erb
new file mode 100644
index 00000000000..0bc44844e78
--- /dev/null
+++ b/lookbook/previews/op_primer/quick_filter_preview/select_panel_single_select.html.erb
@@ -0,0 +1,12 @@
+<%= render(
+      OpPrimer::QuickFilter::SelectPanelComponent.new(
+        name: "Time",
+        query: query,
+        filter_key: :time,
+        path_args: [:meetings],
+        select_variant: :single
+      )
+    ) do |component|
+      component.with_item(label: "Upcoming", value: "future")
+      component.with_item(label: "Past", value: "past")
+    end %>