Introduce possibility to let the server highlight search results for async FilterableTreeView

Author: HDinger

.changeset/cute-yaks-knock.md

@@ -0,0 +1,5 @@
+---
+'@openproject/primer-view-components': minor
+---
+
+Introduce possibility to let the server highlight search results for async FilterableTreeView

app/components/primer/open_project/filterable_tree_view.pcss

@@ -30,13 +30,13 @@ filterable-tree-view {
 
 /* Highlight style for CSS Custom Highlight API */
 ::highlight(primer-filterable-tree-view-search-results) {
-  background-color: var(--bgColor-attention-muted);
+  background-color: var(--display-yellow-scale-2);
 }
 
 /* Fallback: <mark> elements used when CSS Custom Highlight API is unavailable */
 /* stylelint-disable-next-line selector-max-type */
 filterable-tree-view mark {
-  background-color: var(--bgColor-attention-muted);
+  background-color: var(--display-yellow-scale-2);
   color: inherit;
 }
 

app/components/primer/open_project/filterable_tree_view.rb

@@ -189,6 +189,7 @@ class FilterableTreeView < Primer::Component
       DEFAULT_NO_RESULTS_NODE_ARGUMENTS.freeze
 
       # @param src [String] URL of the server endpoint that returns a filtered `<tree-view>` HTML fragment. When set, activates async (server-side) filtering mode. See "Async loading strategy" above.
+      # @param show_search_highlighting [Boolean] Only relevant in async mode (`src:` must be set). When `true` (default), the client highlights matching text using the CSS Custom Highlight API or `<mark>` elements. When `false`, the client skips highlighting entirely; the server is responsible for including highlight markup (e.g. `<mark>` tags) in the returned HTML fragment.
       # @param tree_view_arguments [Hash] Arguments that will be passed to the underlying <%= link_to_component(Primer::Alpha::TreeView) %> component.
       # @param form_arguments [Hash] Form arguments that will be passed to the underlying <%= link_to_component(Primer::Alpha::TreeView) %> component. These arguments allow the selections made within a `FilterableTreeView` to be submitted to the server as part of a Rails form. Pass the `builder:` and `name:` options to this hash. `builder:` should be an instance of `ActionView::Helpers::FormBuilder`, which are created by the standard Rails `#form_with` and `#form_for` helpers. The `name:` option is the desired name of the field that will be included in the params sent to the server on form submission.
       # @param filter_input_arguments [Hash] Arguments that will be passed to the <%= link_to_component(Primer::Alpha::TextField) %> component.
@@ -197,6 +198,7 @@ class FilterableTreeView < Primer::Component
       # @param no_results_node_arguments [Hash] Arguments that will be passed to a <%= link_to_component(Primer::Alpha::TreeView::LeafNode) %> component that appears when no items match the filter criteria.
       def initialize(
         src: nil,
+        show_search_highlighting: true,
         tree_view_arguments: {},
         form_arguments: {},
         filter_input_arguments: {},
@@ -250,6 +252,11 @@ def initialize(
         @system_arguments = deny_tag_argument(**system_arguments)
         @system_arguments[:tag] = :"filterable-tree-view"
         @system_arguments[:src] = src if src
+        @system_arguments[:data] = merge_data(
+          @system_arguments, {
+            data: { show_search_highlighting: false }
+          }
+        ) unless show_search_highlighting
 
         @no_results_node_arguments = no_results_node_arguments.reverse_merge(DEFAULT_NO_RESULTS_NODE_ARGUMENTS)
       end

app/components/primer/open_project/filterable_tree_view.ts

@@ -69,6 +69,10 @@ export class FilterableTreeViewElement extends HTMLElement {
     return !!this.#src
   }
 
+  get #clientHighlightsEnabled(): boolean {
+    return this.getAttribute('data-show-search-highlighting') !== 'false'
+  }
+
   handleEvent(event: Event) {
     if (event.target === this.filterModeControl) {
       this.#handleFilterModeEvent(event)
@@ -372,12 +376,12 @@ export class FilterableTreeViewElement extends HTMLElement {
 
       if (requestWasFiltered) {
         this.#expandAllSubTrees()
-        this.#applyAsyncHighlights(query)
+        if (this.#clientHighlightsEnabled) this.#applyAsyncHighlights(query)
         const hasResults = !!this.treeViewList?.querySelector('[role=treeitem]')
         this.noResultsMessage.toggleAttribute('hidden', hasResults)
         this.treeViewList?.toggleAttribute('hidden', !hasResults)
       } else {
-        this.#removeHighlights()
+        if (this.#clientHighlightsEnabled) this.#removeHighlights()
         this.#restoreExpansionState()
         this.noResultsMessage.setAttribute('hidden', 'hidden')
         this.treeViewList?.removeAttribute('hidden')

app/controllers/primer/view_components/filterable_tree_view_items_controller.rb

@@ -165,12 +165,14 @@ def self.branch(id:, label:, children:)
       def index
         query = params[:query].to_s.strip
         select_variant = (params[:select_variant].presence || "multiple").to_sym
+        server_highlights = params[:server_highlights] == "true"
         nodes = TREE.filter_map { |node| node.filter(query) }
 
         render locals: {
           nodes: nodes,
           query: query,
-          select_variant: select_variant
+          select_variant: select_variant,
+          server_highlights: server_highlights
         }
       end
 

app/views/primer/view_components/filterable_tree_view_items/_node.html.erb

@@ -1,6 +1,20 @@
+<%
+  display_label = if local_assigns[:server_highlights] && query.present?
+    idx = node.label.downcase.index(query.downcase)
+    if idx
+      (h(node.label[0...idx]) +
+        content_tag(:mark, node.label[idx...idx + query.length]) +
+        h(node.label[idx + query.length..])).html_safe
+    else
+      node.label
+    end
+  else
+    node.label
+  end
+%>
 <% if node.leaf? %>
   <% component.with_leaf(
-    label: node.label,
+    label: display_label,
     select_variant: select_variant,
     data: { node_id: node.id }
   ) %>
@@ -22,7 +36,7 @@
     hierarchy_only = query.present? && !node.label.downcase.include?(query.downcase)
   %>
   <% component.with_sub_tree(
-    label: node.label,
+    label: display_label,
     select_variant: select_variant,
     **sub_tree_opts,
     data: {
@@ -32,7 +46,7 @@
   ) do |sub| %>
     <% node.children.each do |child| %>
       <%= render partial: "primer/view_components/filterable_tree_view_items/node",
-                 locals: { component: sub, node: child, query: query, select_variant: select_variant } %>
+                 locals: { component: sub, node: child, query: query, select_variant: select_variant, server_highlights: local_assigns[:server_highlights] } %>
     <% end %>
   <% end %>
 <% end %>

app/views/primer/view_components/filterable_tree_view_items/index.html.erb

@@ -1,6 +1,6 @@
 <%= render(Primer::Alpha::TreeView.new(data: { target: "filterable-tree-view.treeViewList" })) do |tree| %>
   <% nodes.each do |node| %>
     <%= render partial: "primer/view_components/filterable_tree_view_items/node",
-               locals: { component: tree, node: node, query: query, select_variant: select_variant } %>
+               locals: { component: tree, node: node, query: query, select_variant: select_variant, server_highlights: server_highlights } %>
   <% end %>
 <% end %>

previews/primer/open_project/filterable_tree_view_preview.rb

@@ -123,6 +123,18 @@ def async(select_variant: :single)
         })
       end
 
+      # @label Async (with server-side highlighting)
+      #
+      # Demonstrates `show_search_highlighting: false`: the client skips its own highlight logic
+      # and the server is responsible for wrapping matching text in `<mark>` (or other HTML) elements.
+      #
+      # @param select_variant [Symbol] select [multiple, single, none]
+      def async_server_highlights(select_variant: :single)
+        render_with_template(locals: {
+          select_variant: select_variant.to_sym
+        })
+      end
+
       # @label Async form input
       def async_form_input
         render_with_template

previews/primer/open_project/filterable_tree_view_preview/async_server_highlights.html.erb

@@ -0,0 +1,4 @@
+<%= render(Primer::OpenProject::FilterableTreeView.new(
+  show_search_highlighting: false,
+  src: primer_view_components.filterable_tree_view_items_tree_path(select_variant: select_variant, server_highlights: true)
+)) %>

test/components/primer/open_project/filterable_tree_view_test.rb

@@ -274,6 +274,26 @@ def test_custom_filter_modes
         assert_selector "segmented-control li", text: "Foo"
       end
 
+      # ─── show_search_highlighting ──────────────────────────────────────────
+
+      def test_show_search_highlighting_true_by_default_sets_no_data_attribute
+        render_inline(Primer::OpenProject::FilterableTreeView.new)
+
+        assert_selector "filterable-tree-view:not([data-show-search-highlighting])"
+      end
+
+      def test_show_search_highlighting_false_sets_data_attribute
+        render_inline(Primer::OpenProject::FilterableTreeView.new(show_search_highlighting: false))
+
+        assert_selector "filterable-tree-view[data-show-search-highlighting='false']"
+      end
+
+      def test_show_search_highlighting_true_sets_no_data_attribute
+        render_inline(Primer::OpenProject::FilterableTreeView.new(show_search_highlighting: true))
+
+        assert_selector "filterable-tree-view:not([data-show-search-highlighting])"
+      end
+
       # ─── Async mode ────────────────────────────────────────────────────────
 
       def test_src_attribute_is_set_when_src_is_provided