playbook_ui 18.1.0 → 18.2.0.pre.alpha.PLAY3330requiredtypeaheadvalidationbug20501

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_multi_select.jsx

@@ -0,0 +1,44 @@
+import React from 'react'
+import Dropdown from '../_dropdown'
+
+let searchTimer
+let searchController
+
+const loadUsers = (term) => new Promise((resolve, reject) => {
+  clearTimeout(searchTimer)
+  searchController?.abort()
+  const controller = searchController = new AbortController()
+  searchTimer = setTimeout(() => {
+    const params = new URLSearchParams({ q: term, limit: '10', select: 'firstName,lastName' })
+    fetch(`https://dummyjson.com/users/search?${params}`, { signal: controller.signal, credentials: 'omit' })
+      .then((response) => {
+        if (!response.ok) throw new Error('Search failed')
+        return response.json()
+      })
+      .then(({ users }) => resolve(users.map((user) => ({
+        ...user,
+        label: `${user.firstName} ${user.lastName}`,
+        value: user.id,
+      }))))
+      .catch((error) => {
+        if (error.name !== 'AbortError') reject(error)
+      })
+  }, 250)
+})
+
+const DropdownAsyncMultiSelect = () => (
+  <Dropdown
+      activeStyle={{
+        backgroundColor: "bg_light",
+        fontColor: "text_lt_default",
+      }}
+      async
+      autocomplete
+      label="Users"
+      loadOptions={loadUsers}
+      multiSelect
+      placeholder="Try Emily, then Michael"
+  />
+)
+
+export default DropdownAsyncMultiSelect

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_multi_select.md

@@ -0,0 +1,5 @@
+`multiSelect` works with `async` and `autocomplete`, or with `Dropdown.Container searchbar`. 
+
+This example searches DummyJSON's public sample users and waits 250ms after the last keystroke before fetching. Try `Emily`, select a match, then search for `Michael`.
+
+Each selection is added as a Form Pill and the query is cleared. The chosen row stays hidden, including when a later search returns that person again. When `defaultOptions` is set, the menu returns to that list; otherwise it shows the empty message until the next search. Removing a pill or clearing the Dropdown removes that selection. Results are matched by `value`, then `id`, then `label`, so two results with the same label stay distinct. The pills hold the selection, and the input stays empty for the next search.

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_multi_select_rails.html.erb

@@ -0,0 +1,44 @@
+<%= pb_rails("dropdown", props: {
+  id: "async-multi-user-dropdown",
+  label: "Users",
+  name: "async_multi_user",
+  placeholder: "Try Emily, then Michael",
+  autocomplete: true,
+  async: true,
+  multi_select: true,
+  active_style: { background_color: "bg_light", font_color: "text_lt_default" },
+  search_term_minimum_length: 3,
+  search_debounce_timeout: 250,
+  options: [],
+}) %>
+
+<script>
+  (() => {
+    const dropdown = document.getElementById("async-multi-user-dropdown");
+    if (!dropdown || dropdown.dataset.asyncExampleBound) return;
+    dropdown.dataset.asyncExampleBound = "true";
+
+    dropdown.addEventListener("pb:dropdown:search", (event) => {
+      const { searchingFor, setResults, setError } = event.detail;
+      const params = new URLSearchParams({
+        q: searchingFor,
+        limit: "10",
+        select: "firstName,lastName",
+      });
+
+      fetch(`https://dummyjson.com/users/search?${params}`, { credentials: "omit" })
+        .then((response) => {
+          if (!response.ok) throw new Error("User search failed");
+          return response.json();
+        })
+        .then(({ users }) => {
+          setResults(users.map((user) => ({
+            id: user.id,
+            label: `${user.firstName} ${user.lastName}`,
+            value: user.id,
+          })));
+        })
+        .catch(() => setError());
+    });
+  })();
+</script>

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_multi_select_rails.md

@@ -0,0 +1,5 @@
+`multi_select: true` works with `async: true` and either `autocomplete: true` or `searchbar: true`.
+
+Search still waits for `search_term_minimum_length` characters and `search_debounce_timeout` before emitting `pb:dropdown:search`. This example searches [DummyJSON’s public sample users API](https://dummyjson.com/docs/users). Try `Emily`, select a match, then search for `Michael`.
+
+Each selection is added as a Form Pill, the query is cleared, and the loaded results are dropped. Opening the menu again shows the empty message until the next search. `pb:dropdown:selected` emits the full array of selected options. A previously selected id stays hidden when that person appears in a later result list. Removing a pill or clearing the Dropdown removes that selection and emits the remaining array, or `[]` when nothing remains. Removing the last pill with an empty query also drops a later search, so the menu shows the empty message until the next search. The pills hold the selection, and the input stays empty for the next search.

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_rich_results.jsx

@@ -0,0 +1,64 @@
+import React, { useState } from 'react'
+import Dropdown from '../_dropdown'
+import Body from '../../pb_body/_body'
+import Detail from '../../pb_detail/_detail'
+
+let searchTimer
+let searchController
+
+const loadUsers = (term) => new Promise((resolve, reject) => {
+  clearTimeout(searchTimer)
+  searchController?.abort()
+  const controller = searchController = new AbortController()
+  searchTimer = setTimeout(() => {
+    const params = new URLSearchParams({ q: term, limit: '10', select: 'firstName,lastName,company' })
+    fetch(`https://dummyjson.com/users/search?${params}`, { signal: controller.signal, credentials: 'omit' })
+      .then((response) => {
+        if (!response.ok) throw new Error('Search failed')
+        return response.json()
+      })
+      .then(({ users }) => resolve(users.map((user) => ({
+        ...user,
+        label: `${user.firstName} ${user.lastName}`,
+        value: user.id,
+      }))))
+      .catch((error) => {
+        if (error.name !== 'AbortError') reject(error)
+      })
+  }, 250)
+})
+
+const companyDetail = (user) => [user.company?.title, user.company?.department].filter(Boolean).join(' · ')
+
+const renderUser = (user) => (
+  <div>
+    <Body text={user.label} />
+    <Detail text={companyDetail(user)} />
+  </div>
+)
+
+const DropdownAsyncRichResults = () => {
+  const [selected, setSelected] = useState(null)
+
+  return (
+    <Dropdown
+        activeStyle={{
+          backgroundColor: "bg_light",
+          fontColor: "text_lt_default",
+        }}
+        async
+        autocomplete
+        label="User"
+        loadOptions={loadUsers}
+        onSelect={setSelected}
+        placeholder="Try Emily or Michael"
+        renderOption={renderUser}
+        value={selected}
+    >
+      <Dropdown.Trigger customDisplay={selected && <Detail text={companyDetail(selected)} />} />
+      <Dropdown.Container />
+    </Dropdown>
+  )
+}
+
+export default DropdownAsyncRichResults

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_rich_results.md

@@ -0,0 +1,5 @@
+Use `renderOption` to render rich content for each async result. `activeStyle={{ backgroundColor: "bg_light", fontColor: "text_lt_default" }}` is recommended so the selected row uses a light background and default text color. The callback receives the complete option object and returns React content. This example searches DummyJSON's public sample users and displays each user's name, job title, and department.
+
+Dropdown retains the option wrapper, keyboard navigation, disabled behavior, and selection handling. Map each result to include a plain-text `label` for the autocomplete input; selecting an option returns its original data, not its rendered content. Avoid interactive controls inside the renderer because the entire row selects the option. Explicit `Dropdown.Option` children take precedence, and returning `null` or `undefined` falls back to the standard label.
+
+To customize the selected value, pass `customDisplay` to `Dropdown.Trigger`, as with synchronous options. A `Dropdown.Container` without option children displays the async results.

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_search.html.erb

@@ -0,0 +1,43 @@
+<%= pb_rails("dropdown", props: {
+  id: "async-user-dropdown",
+  label: "User",
+  name: "async_user",
+  placeholder: "Try Emily or Michael",
+  autocomplete: true,
+  async: true,
+  active_style: { background_color: "bg_light", font_color: "text_lt_default" },
+  search_term_minimum_length: 3,
+  search_debounce_timeout: 250,
+  options: [],
+}) %>
+
+<script>
+  (() => {
+    const dropdown = document.getElementById("async-user-dropdown");
+    if (!dropdown || dropdown.dataset.asyncExampleBound) return;
+    dropdown.dataset.asyncExampleBound = "true";
+
+    dropdown.addEventListener("pb:dropdown:search", (event) => {
+      const { searchingFor, setResults, setError } = event.detail;
+      const params = new URLSearchParams({
+        q: searchingFor,
+        limit: "10",
+        select: "firstName,lastName",
+      });
+
+      fetch(`https://dummyjson.com/users/search?${params}`, { credentials: "omit" })
+        .then((response) => {
+          if (!response.ok) throw new Error("User search failed");
+          return response.json();
+        })
+        .then(({ users }) => {
+          setResults(users.map((user) => ({
+            id: user.id,
+            label: `${user.firstName} ${user.lastName}`,
+            value: user.id,
+          })));
+        })
+        .catch(() => setError());
+    });
+  })();
+</script>

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_async_search.md

@@ -0,0 +1,55 @@
+Rails Dropdown supports event-driven remote search with `async: true` and either `autocomplete: true` or `searchbar: true`. `active_style: { background_color: "bg_light", font_color: "text_lt_default" }` is recommended so the selected row uses a light background and default text color. Local Dropdown filtering remains unchanged when async is disabled.
+
+Type at least `search_term_minimum_length` characters (default: `3`). After `search_debounce_timeout` milliseconds without another edit (default: `250`), the kit opens the menu, displays a loading message, and emits a bubbling `pb:dropdown:search` event from the Dropdown root. Scope listeners using the root's `id` or `data` attributes.
+
+The event detail contains:
+
+- `searchingFor`: the current query.
+- `setResults(options)`: complete the search with an array of standard Dropdown option objects (`id`, `label`, `value`) or rich `{ option, content }` entries. Use an empty array for no matches.
+- `setError()`: end loading and display a failure message.
+
+The application owns fetching and mapping results. For example, call `fetch(yourUrl).then(...)`, check `response.ok`, map the response to options, pass them to `setResults`, and call `setError` on failure. This example searches [DummyJSON’s public sample users API](https://dummyjson.com/docs/users) over HTTPS without credentials or an API key. Try `Emily` or `Michael`. The API receives the search text and returns up to 10 results; only name fields are requested. HTTP or network failures display the kit’s error state.
+
+Results are displayed without additional local label filtering and without clearing the typed query. When a search returns nothing, earlier results whose labels contain the query stay visible, including text typed after a space. After a single-select autocomplete selection, the input shows that option's label, and opening the menu again shows only retained results whose labels contain that text. With `multi_select: true`, each pick becomes a Form Pill, the query clears, and that row stays hidden. See Async Multi Select. The current results stay in place until the debounced search starts. Callbacks are request-scoped: subsequent edits, selection, clear/reset, dismissal with Escape/Tab or an outside click, and disconnect invalidate pending requests. Dismissing during the debounce delay cancels the search before it starts. Dismissing an in-flight request drops its late response and restores the last results. Opening the menu again searches for the query still in the input. Only the first completion is accepted. Requests that do not complete within 15 seconds display a failure message. The kit ignores stale responses; it does not abort application-owned network requests.
+
+For rich results, `content` is an Element or DocumentFragment cloned into the option wrapper; `option` supplies the label and selection data. See Async Search with Custom Content for a Rails template example.
+
+Async Quick Pick is not supported; Quick Pick uses static date presets.
+
+#### Selection data and defaults
+
+`pb:dropdown:selected` bubbles from the Dropdown root after selection updates. Its existing detail shape is unchanged: the complete option object for single-select, an array for multi-select, and `null` / `[]` when cleared. Custom JSON-serializable fields, nested objects, booleans, and arrays are preserved; rendered rich content is not included. For example, read `event.detail.department_id` to update a dependent field. Numeric IDs retain their type in the event payload; form inputs submit strings.
+
+Selected data is retained independently of remote result rows. A later search returning different options does not discard the selection or its metadata. In multi-select, previously selected IDs remain hidden when they reappear, even if the server returns updated labels or other fields. The selected payload stays as it was when selected until the selection is explicitly changed.
+
+To initialize an async Dropdown before any results load, supply a complete `default_value` option object (an array for multi-select), including `id` and `label`. For example: `async: true, autocomplete: true, options: [], default_value: { id: 42, label: "Ada", department_id: 7 }`. When using `dropdown_field`, pass that explicit default: the builder cannot resolve an initial model ID from an empty options array.
+
+#### Input and reset events
+
+With `async: true`, `pb:dropdown:input` bubbles from the Dropdown root immediately on every edit, including text below the search minimum. Its detail is `{ value, reason }`:
+
+- `reason: "input"`: the autocomplete or search-bar text was edited. `value` is the current text, without debouncing.
+- `reason: "clear"`: the clear control or public `pb:dropdown:clear` command cleared the Dropdown. `value` is `""`.
+- `reason: "reset"`: a native form reset cleared the Dropdown. `value` is `""`.
+
+Selection changes continue to use `pb:dropdown:selected`; choosing an option does not emit an input event. For free-text forms such as a name search, maintain a separate field from both events:
+
+```javascript
+dropdown.addEventListener("pb:dropdown:input", ({ detail }) => {
+  nameField.value = detail.value;
+  // Application-owned IDs can be invalidated on any edit.
+  userIdField.value = "";
+});
+dropdown.addEventListener("pb:dropdown:selected", ({ detail }) => {
+  nameField.value = detail?.label || "";
+  userIdField.value = detail?.id ?? "";
+});
+```
+
+Editing nonempty text retains the Dropdown's selected value until it is changed or cleared. Emptying a single-select autocomplete clears its selected ID and emits `pb:dropdown:selected` with `null`. Emptying a search-bar query does not discard the selected option; emptying a multi-select query does not discard selected pills.
+
+Explicit clear and native form reset clear query text, selection, remote results, loading/error messages, and pending callbacks, and close the menu. They emit the normal cleared selection payload (`null` or `[]`) and the input notification. Native reset completes after the browser resets form controls; a canceled reset leaves kit state intact. Reset clears the selection rather than restoring `default_value`, matching the kit's existing reset convention.
+
+Clicking inside an async Dropdown opens the menu. When no results are available yet, it shows the empty message until the debounced search starts and replaces it with loading, results, or an error. An async search-bar menu stays open so its input remains accessible.
+
+The clear control is also available for an unselected async query unless `clearable: false`. No async input notifications, remote-result cleanup, or changed reset timing are applied to synchronous Dropdowns.

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_controlled_selection.jsx

@@ -0,0 +1,42 @@
+import React, { useState } from 'react'
+import Button from '../../pb_button/_button'
+import Dropdown from '../_dropdown'
+import Flex from '../../pb_flex/_flex'
+
+const options = [
+  { id: 'engineering', label: 'Engineering', value: 'engineering' },
+  { id: 'operations', label: 'Operations', value: 'operations' },
+  { id: 'sales', label: 'Sales', value: 'sales' },
+]
+
+const DropdownControlledSelection = (props) => {
+  const [selected, setSelected] = useState([])
+
+  return (
+    <>
+      <Dropdown
+          label="Departments"
+          marginBottom="sm"
+          multiSelect
+          onSelect={setSelected}
+          options={options}
+          value={selected}
+          {...props}
+      />
+      <Flex gap="xs">
+        <Button
+            onClick={() => setSelected(options)}
+            text="Select All"
+            variant="secondary"
+        />
+        <Button
+            onClick={() => setSelected([])}
+            text="Clear"
+            variant="secondary"
+        />
+      </Flex>
+    </>
+  )
+}
+
+export default DropdownControlledSelection

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_controlled_selection.md

@@ -0,0 +1,5 @@
+Pass `value` to control selection from React state. Use an option object or `null` for single selection, and an array of option objects for multi-selection. Dropdown emits a proposed selection through `onSelect` and the existing `onChange({ target: { name, value } })` callback; the parent must update `value` to accept it. Clear and pill removal follow the same rule. Updating `value` itself does not emit a selection callback.
+
+Use `value` when something other than the Dropdown changes the selection after mount, such as the buttons in this example, a form library reset, or data loaded after the form renders. `defaultValue` is only read on mount.
+
+Selected objects retain their custom and nested data, even when absent from the current options or remote results. `value` takes precedence over `defaultValue`. Omit `value` to retain the existing uncontrolled behavior; use `null` or `[]`, rather than `undefined`, to clear a controlled selection.

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_external_search.jsx

@@ -0,0 +1,58 @@
+import React, { useEffect, useState } from 'react'
+import Dropdown from '../_dropdown'
+
+const DropdownExternalSearch = () => {
+  const [query, setQuery] = useState('')
+  const [options, setOptions] = useState([])
+  const [loading, setLoading] = useState(false)
+  const [selected, setSelected] = useState(null)
+
+  useEffect(() => {
+    const controller = new AbortController()
+    setOptions([])
+    setLoading(false)
+    if (query.length < 3) return () => controller.abort()
+    setLoading(true)
+    const timer = setTimeout(() => {
+      const params = new URLSearchParams({ q: query, limit: '10', select: 'firstName,lastName' })
+      fetch(`https://dummyjson.com/users/search?${params}`, { signal: controller.signal, credentials: 'omit' })
+        .then((response) => {
+          if (!response.ok) throw new Error('Search failed')
+          return response.json()
+        })
+        .then(({ users }) => {
+          if (!controller.signal.aborted) setOptions(users.map((user) => ({
+            ...user,
+            label: `${user.firstName} ${user.lastName}`,
+            value: user.id,
+          })))
+        })
+        .catch(() => { if (!controller.signal.aborted) setOptions([]) })
+        .finally(() => { if (!controller.signal.aborted) setLoading(false) })
+    }, 250)
+    return () => { clearTimeout(timer); controller.abort() }
+  }, [query])
+
+  return (
+    <form>
+      <Dropdown
+          activeStyle={{
+            backgroundColor: "bg_light",
+            fontColor: "text_lt_default",
+          }}
+          async
+          autocomplete
+          label="User"
+          loading={loading}
+          onInputChange={(text, { reason }) => setQuery(reason === 'input' ? text : '')}
+          onSelect={setSelected}
+          options={options}
+          placeholder="Try Emily or Michael"
+          value={selected}
+      />
+
+    </form>
+  )
+}
+
+export default DropdownExternalSearch

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_external_search.md

@@ -0,0 +1,9 @@
+`onInputChange(text, { reason })` reports typing immediately with reason `input`, and an empty query with reason `clear` on explicit clear. `activeStyle={{ backgroundColor: "bg_light", fontColor: "text_lt_default" }}` is recommended so the selected row uses a light background and default text color. Selecting an option and prop-driven selection changes do not emit input events. This example stores the selection with `onSelect` and keeps the fetched options, so opening the menu again can show labels that contain the selected label. Clear the application query from `onSelect` only when that list should be dropped.
+
+Async mode or opting into `onInputChange` keeps the selected option while typing a nonempty query. Emptying a single-select autocomplete proposes an empty selection through the existing selection callbacks. Emptying a search-bar query or multi-select query preserves the selection. Controlled `value` remains owned by the parent.
+
+For externally managed fetching, pass `async`, `options`, and optionally `loading`, without `loadOptions`. Dropdown displays these results without local label filtering. After a single-select autocomplete selection, opening the menu again shows only results whose labels contain the selected label now in the input. The application owns debounce, minimum query length, errors, cancellation, and stale-response protection. When the menu is open, a new result list focuses the first match, so Enter selects it; ArrowDown and ArrowUp still move through the list. This example uses an abortable DummyJSON request. When `loadOptions` is supplied, Dropdown owns the result list instead and focuses the first match the same way.
+
+Form libraries reset selection by updating controlled `value`. The existing `ref.clearSelected()` clears an uncontrolled selection and emits the `clear` input reason. React Dropdown does not add native form-reset handling.
+
+Without the new props, existing input behavior stays unchanged. In async mode or with `onInputChange`, the clear icon is also available for a nonempty query before an option has been selected.

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_no_options_text.html.erb

@@ -0,0 +1,9 @@
+<%
+  options = [
+    { label: 'United States', value: 'unitedStates', id: 'us' },
+    { label: 'Canada', value: 'canada', id: 'ca' },
+    { label: 'Pakistan', value: 'pakistan', id: 'pk' },
+  ]
+%>
+
+<%= pb_rails("dropdown", props: { autocomplete: true, label: "Country", no_options_text: "No matching countries", options: options }) %>

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_no_options_text.jsx

@@ -0,0 +1,35 @@
+import React from 'react'
+import Dropdown from '../../pb_dropdown/_dropdown'
+
+const DropdownNoOptionsText = (props) => {
+
+  const options = [
+    {
+      label: "United States",
+      value: "unitedStates",
+      id: "us"
+    },
+    {
+      label: "Canada",
+      value: "canada",
+      id: "ca"
+    },
+    {
+      label: "Pakistan",
+      value: "pakistan",
+      id: "pk"
+    }
+  ];
+
+  return (
+    <Dropdown
+        autocomplete
+        label="Country"
+        noOptionsText="No matching countries"
+        options={options}
+        {...props}
+    />
+  )
+}
+
+export default DropdownNoOptionsText

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_no_options_text_rails.md

@@ -0,0 +1,3 @@
+Use `no_options_text` to replace the message shown when there are no options to display. Type a country that is not listed to see it.
+
+It applies when filtering matches no options, when an `async` search returns no results, when an async Dropdown is opened before searching, and when the Dropdown renders without options. Without it, Dropdown shows "no option" for filtered options and "No results found" for async searches.

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_no_options_text_react.md

@@ -0,0 +1,3 @@
+Use `noOptionsText` to replace the message shown when there are no options to display. Type a country that is not listed to see it.
+
+It applies when filtering matches no options and when an `async` search returns no results or the Dropdown is opened before searching. Without it, Dropdown shows "no option" for filtered options and "No results found" for async searches.

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_quickpick_custom.md

@@ -1,10 +1,15 @@
 The `customQuickPickDates` prop allows for defining custom quick pick date options for the dropdown. The prop accepts an object with two properties: `dates` and `override`.
 
 **The `dates` property** accepts an array of objects. Each object has `label` and `value` properties. The `label` is what will be displayed in the dropdown menu. The `value` property defines the date range that will be selected, and can be:
-- An array of two date strings representing a specific range (e.g., `["06/01/2022", "06/07/2022"]`)
+- An array of two date strings (or `Date` objects) representing a specific range (e.g., `["06/01/2022", "06/07/2022"]`).
+  - **Date-only** strings get start-of-day / end-of-day when synced to `enableTime` DatePickers.
+  - **Timed** strings use the same formats as Rails QuickPick customs:
+    - US `m/d/Y` + time (optional `:SS`, optional `AM`/`PM`) — wall-clock; emit offset-less `YYYY-MM-DDTHH:MM:SS`
+    - Offset-less `YYYY-MM-DDTHH:MM:SS` — wall-clock; emit offset-less
+    - ISO-8601 with `Z` or numeric offset — absolute instant; emit keeps offset/`Z` so `new Date(iso)` preserves the instant
+  - `Date` objects keep their authored time (including intentional midnight / `23:59:00`).
 - An object with `timePeriod` and `amount` properties for dynamic date calculations:
   - The `timePeriod` property accepts `"days"`, `"weeks"`, `"months"`, `"quarters"`, or `"years"`, representing past time periods calculated from today.
   - The `amount` property accepts any number.
 
 **The `override` property** is a boolean that controls whether custom dates replace or append to the default quick pick options. Default is `true` (replaces defaults). Set to `false` to append your custom dates to the default quick pick options.
-

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_quickpick_custom_rails.md

@@ -1,10 +1,15 @@
 The `custom_quick_pick_dates` prop allows for defining custom quick pick date options for the dropdown. The prop accepts an object with two properties: `dates` and `override`.
 
 **The `dates` property** accepts an array of objects. Each object has `label` and `value` properties. The `label` is what will be displayed in the dropdown menu. The `value` property defines the date range that will be selected, and can be:
-- An array of two date strings representing a specific range (e.g., `["06/01/2022", "06/07/2022"]`)
+- An array of two date strings representing a specific range (e.g., `["06/01/2022", "06/07/2022"]`).
+  - **Date-only** strings stay date-only on the option payload (SOD/EOD applied at sync when `enable_time`).
+  - **Timed** strings use the same formats as React QuickPick customs:
+    - US `m/d/Y` + time (optional `:SS`, optional `AM`/`PM`) — wall-clock (e.g. `"06/01/2022 9:30 AM"`); emit offset-less `YYYY-MM-DDTHH:MM:SS`
+    - Offset-less `YYYY-MM-DDTHH:MM:SS` — wall-clock (e.g. `"2026-03-08T02:30:00"`); emit offset-less
+    - ISO-8601 with `Z` or numeric offset — absolute instant; emit keeps offset/`Z` (e.g. `…+00:00` / `…-05:00`) so JS `new Date(iso)` preserves the same instant
+  - Wall-clock and absolute emit differ on purpose: offset-less keeps the authored clock face; offset-bearing strings keep the absolute instant across Rails ↔ React. Unsupported timed free text raises.
 - An object with `time_period` and `amount` properties for dynamic date calculations:
   - The `time_period` property accepts `"days"`, `"weeks"`, `"months"`, `"quarters"`, or `"years"`, representing past time periods calculated from today.
   - The `amount` property accepts any number.
 
 **The `override` property** is a boolean that controls whether custom dates replace or append to the default quick pick options. Default is `true` (replaces defaults). Set to `false` to append your custom dates to the default quick pick options.
-

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_quickpick_enable_time.html.erb

@@ -0,0 +1,33 @@
+<%= pb_rails("dropdown", props: {
+  id: "dropdown-quickpick-enable-time",
+  label: "Date Range",
+  name: "date_range_enable_time",
+  margin_bottom: "sm",
+  variant: "quickpick",
+  controls_start_id: "start-date-picker-enable-time",
+  controls_end_id: "end-date-picker-enable-time",
+  start_date_id: "quickpick_enable_time_start_date",
+  start_date_name: "start_date_enable_time",
+  end_date_id: "quickpick_enable_time_end_date",
+  end_date_name: "end_date_enable_time"
+}) %>
+
+<%= pb_rails("date_picker", props: {
+  picker_id: "start-date-picker-enable-time",
+  label: "Start Date",
+  name: "start_date_picker_enable_time",
+  placeholder: "Select Start Date",
+  enable_time: true,
+  close_on_select: false,
+  sync_start_with: "dropdown-quickpick-enable-time"
+}) %>
+
+<%= pb_rails("date_picker", props: {
+  picker_id: "end-date-picker-enable-time",
+  label: "End Date",
+  name: "end_date_picker_enable_time",
+  placeholder: "Select End Date",
+  enable_time: true,
+  close_on_select: false,
+  sync_end_with: "dropdown-quickpick-enable-time"
+}) %>

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_quickpick_enable_time.jsx

@@ -0,0 +1,42 @@
+import React from "react";
+import Dropdown from "../../pb_dropdown/_dropdown";
+import DatePicker from "../../pb_date_picker/_date_picker";
+
+const DropdownQuickpickEnableTime = (props) => {
+  return (
+    <>
+      <Dropdown
+          {...props}
+          controlsEndId="end-date-picker-enable-time"
+          controlsStartId="start-date-picker-enable-time"
+          id="dropdown-quickpick-enable-time"
+          label="Range"
+          marginBottom="sm"
+          placeholder="Select a Date Range"
+          variant="quickpick"
+      />
+
+      <DatePicker
+          {...props}
+          enableTime
+          initializeOnce
+          label="Start Date"
+          pickerId="start-date-picker-enable-time"
+          placeholder="Select a Start Date"
+          syncStartWith="dropdown-quickpick-enable-time"
+      />
+
+      <DatePicker
+          {...props}
+          enableTime
+          initializeOnce
+          label="End Date"
+          pickerId="end-date-picker-enable-time"
+          placeholder="Select an End Date"
+          syncEndWith="dropdown-quickpick-enable-time"
+      />
+    </>
+  );
+};
+
+export default DropdownQuickpickEnableTime;

data/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_quickpick_enable_time.md

@@ -0,0 +1,24 @@
+When linked DatePickers use `enable_time` / `enableTime`, QuickPick presets that do not include an explicit time apply **start of day** (12:00 AM) to the start picker and **end of day** (11:59 PM) to the end picker. That matches DatePicker minute precision and inclusive datetime filters for ranges like Today and Yesterday.
+
+**Supported timed custom formats (Rails and React — same contract):**
+
+| Format | Example | Semantics |
+|--------|---------|-----------|
+| US `m/d/Y` + time (optional `:SS`, optional `AM`/`PM`) | `"06/01/2022 9:30 AM"` | Wall-clock — literal hour/minute/second labels |
+| Offset-less ISO datetime (`T` separator) | `"2026-03-08T02:30:00"` | Wall-clock — same as above (not server-TZ) |
+| ISO-8601 with `Z` or numeric offset | `"2026-03-08T07:30:00Z"`, `"2026-03-08T02:30:00-05:00"` | Absolute instant |
+
+**Emit (Rails and React — same contract):**
+
+| Input kind | Emit |
+|------------|------|
+| Wall-clock (US `m/d/Y` + time, or offset-less `YYYY-MM-DDTHH:MM:SS`) | Offset-less `YYYY-MM-DDTHH:MM:SS` — authored clock face |
+| Absolute (`Z` or numeric offset) | Keeps offset / `Z` (e.g. `…Z` or `…±HH:MM`) so `parseQuickPickDateTime` / `new Date(iso)` preserve the same instant |
+
+React also accepts `Date` objects (times kept as authored, including intentional midnight / `23:59:00`).
+
+Date-only custom strings (e.g. `"06/01/2022"`) still get SOD/EOD at sync when `enableTime` is on. Other free-text / undocumented timed strings are not supported.
+
+On Rails, wall-clock customs go to the option payload as offset-less datetimes; absolute customs keep their offset so linked `enableTime` DatePickers sync to the correct instant (not a misread local wall-clock).
+
+Alternate configuration: QuickPick + Time can also be handled by a Date-only QuickPick (Dropdown QuickPick + two DatePickers without time selection) paired with two TimePickers for start + end time selection in the same form.