Add some documentation for advanced filters. wp/74380

app/forms/filters/inputs/date_form.rb

@@ -41,6 +41,11 @@ class Filters::Inputs::DateForm < Filters::Inputs::BaseFilterForm
     from_value = fmt == "between-dates" ? filter_values.fetch(0, "") : nil
     to_value = fmt == "between-dates" ? filter_values.fetch(1, "") : nil
 
+    # The multi name intentionally uses @filter.name (not operand_name) because
+    # parseDateFilterValue in filters-form.controller.ts locates the datepicker
+    # inputs via findTargetById(filterName, …), which matches the id derived from
+    # the multi name. Switching to operand_name would require migrating that
+    # lookup to findTargetByName and adding data-filter-name to the picker inputs.
     group.multi(name: filter_name, label: filter_name, visually_hide_label: true,
                 class: ["advanced-filters--filter-value"],
                 data: {

lookbook/previews/open_project/common/advanced_form_inputs_preview.rb

@@ -55,6 +55,30 @@ module OpenProject
       def check_box_group_with_include_hidden
         render_with_template
       end
+
+      # **SegmentedControlInput**
+      #
+      # A Primer `SegmentedControl` backed by a plain `<input type="hidden">`.
+      # The hidden field is the source of truth for form submission: when the
+      # user selects a segment, the `filter--segmented-control` Stimulus
+      # controller reacts to Primer's `itemActivated` event, writes the chosen
+      # `data-value` into the hidden field, and dispatches a `change` event so
+      # that any ancestor change listener (e.g. `filter--filters-form`) can
+      # react without knowing about the segmented control at all.
+      #
+      # The first item is selected by default when `value:` is nil or absent.
+      def segmented_control_input_multi
+        render_with_template
+      end
+
+      # **SegmentedControlInput — boolean toggle**
+      #
+      # A special case of `SegmentedControlInput` with exactly two items
+      # mimicking a toggle switch. Used for boolean filters where the backing
+      # values are `"t"` (yes) and `"f"` (no).
+      def segmented_control_input_boolean
+        render_with_template
+      end
     end
   end
 end

lookbook/previews/open_project/common/advanced_form_inputs_preview/segmented_control_input_boolean.html.erb

@@ -0,0 +1,21 @@
+<%
+  the_form = Class.new(ApplicationForm) do
+    form do |f|
+      f.segmented_control(
+        name: :recurring,
+        label: "Part of a meeting series",
+        value: "f",
+        items: [
+          { value: "f", label: I18n.t("general_text_No") },
+          { value: "t", label: I18n.t("general_text_Yes") }
+        ]
+      )
+
+      f.submit(name: "submit", label: "Save")
+    end
+  end
+%>
+
+<%= primer_form_with(url: "/abc", method: :post) do |f|
+  render(the_form.new(f))
+end %>

lookbook/previews/open_project/common/advanced_form_inputs_preview/segmented_control_input_multi.html.erb

@@ -0,0 +1,22 @@
+<%
+  the_form = Class.new(ApplicationForm) do
+    form do |f|
+      f.segmented_control(
+        name: :priority,
+        label: "Priority",
+        value: "normal",
+        items: [
+          { value: "low",    label: "Low" },
+          { value: "normal", label: "Normal" },
+          { value: "high",   label: "High" }
+        ]
+      )
+
+      f.submit(name: "submit", label: "Save")
+    end
+  end
+%>
+
+<%= primer_form_with(url: "/abc", method: :post) do |f|
+  render(the_form.new(f))
+end %>