[PBNTR-798] Make Date Picker Work within Turbo Frames (#4142)

**What does this PR do?** A clear and concise description with your
runway ticket url.
[PBNTR-798](https://runway.powerhrg.com/backlog_items/PBNTR-798) is a
follow up to the investigation in
[PBNTR-573](https://runway.powerhrg.com/backlog_items/PBNTR-573). It
adds a `custom_event_type` prop which can be used as a hook for a dev to
get any desired event (e.g. click, keyboard, or Turbo) to re-trigger a
DOMContentLoaded event. Nitro devs can use this to update the value of a
Rails DatePicker without reloading the entire page.

**Screenshots:** Screenshots to visualize your addition/change
<img width="1611" alt="doc ex and console after solve console errors"
src="https://github.com/user-attachments/assets/52b4f696-d94d-47da-8c63-01a8d8dd43a5"
/>



**How to test?** Steps to confirm the desired behavior:
1. Go to Rails DatePicker page - [Within Turbo Frames doc
example](https://pr4142.playbook.beta.px.powerapp.cloud/kits/date_picker#within-turbo-frames).
2. Click on the DatePicker, it should work as usual. The button click
should submit a console log. This doc example is not fully wired up like
it would be in a real world application, this is just a demonstration.
3. Other datepickers on the page should also work as expected.


#### Checklist:
- [x] **LABELS** Add a label: `enhancement`, `bug`, `improvement`, `new
kit`, `deprecated`, or `breaking`. See [Changelog &
Labels](https://github.com/powerhome/playbook/wiki/Changelog-&-Labels)
for details.
- [x] **DEPLOY** I have added the `milano` label to show I'm ready for a
review.
~~- [ ] **TESTS** I have added test coverage to my code.~~

Author: ElisaShapiro

Diff for: playbook/app/pb_kits/playbook/pb_date_picker/date_picker.html.erb

@@ -64,18 +64,30 @@
   </div>
 
   <%= javascript_tag do %>
-    window.addEventListener("DOMContentLoaded", () => {
-      datePickerHelper(<%= object.date_picker_config %>, "<%= object.scroll_container %>")
+    (function() {
+      const loadDatePicker = () => {
+        datePickerHelper(<%= object.date_picker_config %>, "<%= object.scroll_container %>")
 
-      if (<%= object.selection_type == "quickpick" %>) {
-        document.getElementById("<%= object.picker_id %>").addEventListener("change", ({ target }) => {
-          const startDate = document.getElementById("<%= object.start_date_id %>")
-          const endDate = document.getElementById("<%= object.end_date_id %>")
-          const splittedValue = target.value.split(" to ")
-          startDate.value = splittedValue[0]
-          endDate.value = splittedValue[1] ? splittedValue[1] : splittedValue[0]
+        if (<%= object.selection_type == "quickpick" %>) {
+          document.getElementById("<%= object.picker_id %>").addEventListener("change", ({ target }) => {
+            const startDate = document.getElementById("<%= object.start_date_id %>")
+            const endDate = document.getElementById("<%= object.end_date_id %>")
+            const splittedValue = target.value.split(" to ")
+            startDate.value = splittedValue[0]
+            endDate.value = splittedValue[1] ? splittedValue[1] : splittedValue[0]
+          })
+        }
+      }
+
+      window.addEventListener("DOMContentLoaded", () => {
+        loadDatePicker()
+      })
+
+      if (<%= !object.custom_event_type.empty? %>) {
+        window.addEventListener("<%= object.custom_event_type %>", () => {
+          loadDatePicker()
         })
       }
-    })
+    })()
   <% end %>
 <% end %>

Diff for: playbook/app/pb_kits/playbook/pb_date_picker/date_picker.rb

@@ -73,6 +73,8 @@ class DatePicker < Playbook::KitBase
                       default: false
       prop :year_range, type: Playbook::Props::Array,
                         default: [1900, 2100]
+      prop :custom_event_type, type: Playbook::Props::String,
+                               default: ""
 
       def classname
         default_margin_bottom = margin_bottom.present? ? "" : " mb_sm"

Diff for: playbook/app/pb_kits/playbook/pb_date_picker/docs/_date_picker_turbo_frames.html.erb

@@ -0,0 +1,13 @@
+<%= pb_rails("date_picker", props: { picker_id: "date-picker-turbo-frames", custom_event_type: "datePickerLoader" }) %>
+<%= pb_rails("button", props: { id: "date-picker-loader", text: "Click Event Simulation" }) %>
+
+<script>
+    document.getElementById("date-picker-loader").addEventListener("click", () => {
+        window.document.dispatchEvent(
+            new CustomEvent("datePickerLoader", {
+                bubbles: true,
+            })
+        )
+        console.log("Event 'datePickerLoader' dispatched - in a real implementation, this event would trigger the date picker's reinitialization through the custom_event_type prop connection")
+    })
+</script>

Diff for: playbook/app/pb_kits/playbook/pb_date_picker/docs/_date_picker_turbo_frames_rails.md

@@ -0,0 +1,3 @@
+The `custom_event_type` prop allows you to specify a custom event that will trigger the date picker's initialization, in addition to the default initialization on `DOMContentLoaded`. This is particularly useful in dynamic contexts like Turbo Frame updates where you need to reinitialize the date picker after new content loads. For Turbo integration, use `custom_event_type: "turbo:before-render"` to ensure the date picker properly reinitializes after Turbo navigation events. 
+
+In this example, we demonstrate the setup pattern by connecting a button to dispatch a "datePickerLoader" event - while the date picker's event listener is properly configured through the `custom_event_type` prop, this demo only logs the event dispatch to the console to illustrate the connection structure.

Diff for: playbook/app/pb_kits/playbook/pb_date_picker/docs/example.yml

@@ -28,6 +28,7 @@ examples:
   - date_picker_time: Time Selection
   - date_picker_positions: Custom Positions
   - date_picker_positions_element: Custom Position (based on element)
+  - date_picker_turbo_frames: Within Turbo Frames
 
   react:
   - date_picker_default: Default