playbook_ui 18.0.0.pre.alpha.play3194filtericons19569 → 18.0.0.pre.alpha.play316819703

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 330ed574153c52e60a6a982377e431077777c579faefe56364b21890f76a1e11
-  data.tar.gz: 7a1993dd4be0cd0e4c95378b02017f0235382605363b8a619800efdb84185d1e
+  metadata.gz: d786f7aa30fa9c245ffabc812b1f4cc4eec3c066fa9e7e927ca02cde72bdbbf0
+  data.tar.gz: 5266e40cbf6df3c53f75013c6d8377bfdc66198703316aced89f93d7d2534321
 SHA512:
-  metadata.gz: ee505f4628c702e0f5a18e8dc683a2a1782399cbb70e237e2c5f41cbe102eb8c6d26fa75e5e3d68cc3664bd619009146b630172c4f54c5ff22ebe86679f9faa8
-  data.tar.gz: 71f9edfe85aa25da65d7edc908d9035c2f336d62f2c46008a56d1746301d27c707eea64cbe26119ad7d606f685df6621bd3b922c5c52dbe4c5d3bb671b8d06a0
+  metadata.gz: db68dc179c9f281f22230e7bbb95c2ecf72c74376c0a39b6d94cc5ddf6f5b86383302cb83c96e385cfa764edf0a11e752e8e19860ba4eacb70e2b320b3424ca9
+  data.tar.gz: b765470abaf7b8e2d16a74e01faad0e4092ab40773984e0127a2d62444b0040636c2e1547225700e9fd2616af079775a82c1457b3f7138cb47ec55e588a7df01

data/app/pb_kits/playbook/pb_background/_background.tsx

@@ -98,7 +98,7 @@ const Background = (props: BackgroundProps): React.ReactElement => {
     imageUrl: getResponsiveValue(imageUrl),
   });
 
-  // Update responsive values on window resize.
+  // Keep responsive values in sync when props change, and on window resize.
   useEffect(() => {
     const updateResponsiveProps = () => {
       setResponsiveProps({
@@ -109,6 +109,7 @@ const Background = (props: BackgroundProps): React.ReactElement => {
         imageUrl: getResponsiveValue(imageUrl),
       });
     };
+    updateResponsiveProps();
     window.addEventListener('resize', updateResponsiveProps);
     return () => window.removeEventListener('resize', updateResponsiveProps);
   }, [backgroundSize, backgroundPosition, backgroundRepeat, backgroundColor, imageUrl]);
@@ -153,6 +154,8 @@ const Background = (props: BackgroundProps): React.ReactElement => {
     ...dynamicInlineProps
   };
 
+  // Dynamic HTML tag from props; matches other kits (Title, Collapsible, etc.).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const Tag: React.ReactElement | any = `${tag}`;
   const ariaProps = buildAriaProps(aria);
   const dataProps = buildDataProps(data);

data/app/pb_kits/playbook/pb_background/background.test.js

@@ -1,4 +1,5 @@
-import { ensureAccessible, renderKit } from '../utilities/test-utils'
+import React from 'react'
+import { ensureAccessible, render, renderKit } from '../utilities/test-utils'
 
 import Background from './_background'
 
@@ -20,6 +21,27 @@ test('backgroundColor = category_1', () => {
   expect(kit).toHaveClass('pb_background_kit pb_background_color_category_1')
 })
 
+test('updates backgroundColor class when the prop changes', () => {
+  const { getByTestId, rerender } = render(
+    <Background
+        backgroundColor="info_subtle"
+        data={{ testid: 'background' }}
+    />
+  )
+
+  expect(getByTestId('background')).toHaveClass('pb_background_color_info_subtle')
+
+  rerender(
+    <Background
+        backgroundColor="card_light"
+        data={{ testid: 'background' }}
+    />
+  )
+
+  expect(getByTestId('background')).toHaveClass('pb_background_color_card_light')
+  expect(getByTestId('background')).not.toHaveClass('pb_background_color_info_subtle')
+})
+
 test('customColor prop styles background color with a hex value', () => {
   const kit = renderKit(Background, props, { customColor: '#1d99a8' })
 

data/app/pb_kits/playbook/pb_copy_button/_copy_button.tsx

@@ -1,6 +1,6 @@
 import React from 'react'
 import classnames from 'classnames'
-import { buildAriaProps, buildCss, buildDataProps } from '../utilities/props'
+import { buildAriaProps, buildCss, buildDataProps, buildHtmlProps } from '../utilities/props'
 import { globalProps } from '../utilities/globalProps'
 
 import Button from '../pb_button/_button'
@@ -13,6 +13,7 @@ type CopyButtonProps = {
   aria?: { [key: string]: string }
   className?: string
   data?: { [key: string]: string }
+  htmlOptions?: {[key: string]: string | number | boolean | (() => void)}
   id?: string
   from?: string
   text?: string
@@ -29,6 +30,7 @@ const CopyButton = (props: CopyButtonProps) => {
     className,
     data = {},
     from = '',
+    htmlOptions = {},
     id,
     text = 'Copy',
     timeout = 1000,
@@ -42,12 +44,14 @@ const CopyButton = (props: CopyButtonProps) => {
 
   const ariaProps = buildAriaProps(aria)
   const dataProps = buildDataProps(data)
+  const htmlProps = buildHtmlProps(htmlOptions)
   const classes = classnames(buildCss('pb_copy_button_kit'), globalProps(props), className)
 
   return (
     <div 
         {...ariaProps}
         {...dataProps}
+        {...htmlProps}
         className={classes}
         id={id}
     >

data/app/pb_kits/playbook/pb_copy_button/copy_button.test.jsx

@@ -86,3 +86,15 @@ test('passes text and tooltip props to button', () => {
   const tooltip = kit.querySelector('.pb_tooltip_kit')
   expect(tooltip).toBeInTheDocument()
 })
+
+test('applies htmlOptions to the root element', () => {
+  render(
+      <CopyButton
+          data={{ testid: 'html-options-test' }}
+          htmlOptions={{ title: 'copy title' }}
+          value="copy"
+      />
+  )
+
+  expect(screen.getByTestId('html-options-test')).toHaveAttribute('title', 'copy title')
+})

data/app/pb_kits/playbook/pb_date_time_stacked/_date_time_stacked.tsx

@@ -1,5 +1,6 @@
 
 import React from 'react'
+import classnames from 'classnames'
 
 import { buildCss, buildHtmlProps } from '../utilities/props'
 import { deprecatedProps, globalProps } from '../utilities/globalProps'
@@ -11,6 +12,7 @@ import TimeStacked from '../pb_time_stacked/_time_stacked'
 import DateStacked from '../pb_date_stacked/_date_stacked'
 
 type DateTimeStackedProps = {
+  className?: string,
   htmlOptions?: {[key: string]: string | number | boolean | (() => void)},
   id?: string,
   date: Date,
@@ -27,20 +29,25 @@ const DateTimeStacked = (props: DateTimeStackedProps): React.ReactElement => {
     date,
     datetime,
     dark,
+    className,
     htmlOptions = {},
     timeZone = 'America/New_York',
     showCurrentYear = false,
   } = props
 
-  const classes = buildCss('pb_date_time_stacked_kit', globalProps(props))
-  const htmlProps = buildHtmlProps(htmlOptions)
+  const classes = classnames(
+    buildCss('pb_date_time_stacked_kit'),
+    globalProps(props),
+    className
+  )
 
   return (
     <Flex
+        htmlOptions={htmlOptions}
         inline={false}
         vertical="stretch"
-        {...htmlProps}
         {...props}
+        className={classes}
     >
       <FlexItem>
         <DateStacked
@@ -58,7 +65,6 @@ const DateTimeStacked = (props: DateTimeStackedProps): React.ReactElement => {
       />
       <FlexItem>
         <TimeStacked
-            className={classes}
             dark={dark}
             date={date || datetime}
             timeZone={timeZone}

data/app/pb_kits/playbook/pb_date_time_stacked/date_time_stacked.test.js

@@ -74,3 +74,15 @@ test('hides current year by default', () => {
     expect(yearElement).toBeNull()
   }
 })
+
+test('applies kit class and global props to the root', () => {
+  const kit = renderKit(DateTimeStacked, {
+    data: { testid: 'datetimestacked-root' },
+    datetime,
+    dark: false,
+    margin: 'md',
+  })
+
+  expect(kit).toHaveClass('pb_date_time_stacked_kit')
+  expect(kit).toHaveClass('m_md')
+})

data/app/pb_kits/playbook/pb_dialog/child_kits/_dialog_body.tsx

@@ -1,22 +1,27 @@
 import React from 'react'
 import classnames from 'classnames'
-import { buildCss } from '../../utilities/props'
+import { buildCss, buildHtmlProps } from '../../utilities/props'
 import { globalProps } from '../../utilities/globalProps'
 
 type DialogBodyProps = {
   children: React.ReactNode | React.ReactNode[] | string,
   padding?: "xxs" | "xs" | "sm" | "md" | "lg" | "xl",
-  className?: string
+  className?: string,
+  htmlOptions?: {[key: string]: string | number | boolean | (() => void)},
 } 
 
 // Body component
 const DialogBody = (props: DialogBodyProps): React.ReactElement => {
-  const { children, className } = props
+  const { children, className, htmlOptions = {} } = props
   const bodyCSS = buildCss("dialog_body")
   const bodySpacing = globalProps(props)
+  const htmlProps = buildHtmlProps(htmlOptions)
 
   return (
-    <div className={classnames(bodyCSS, bodySpacing, className)}>
+    <div
+        {...htmlProps}
+        className={classnames(bodyCSS, bodySpacing, className)}
+    >
       {children}
     </div>
   )

data/app/pb_kits/playbook/pb_dialog/dialog.test.jsx

@@ -268,3 +268,13 @@ describe('isNativeSelectMenuInteraction', () => {
     expect(isNativeSelectMenuInteraction(dialog, select)).toBe(false)
   })
 })
+
+test("applies htmlOptions to Dialog.Body", () => {
+  render(
+    <Dialog.Body htmlOptions={{ title: "body title" }}>
+      {"Body content"}
+    </Dialog.Body>
+  )
+
+  expect(document.querySelector(".dialog_body")).toHaveAttribute("title", "body title")
+})

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

@@ -0,0 +1,57 @@
+<%= pb_rails("dropdown", props: {
+  id: "async-rich-user-dropdown",
+  label: "User",
+  name: "async_rich_user",
+  placeholder: "Try Emily or Michael",
+  autocomplete: true,
+  async: true,
+  options: [],
+}) %>
+
+<template id="async-user-option-template">
+  <%= pb_rails("flex", props: { orientation: "column", align: "start" }) do %>
+    <%= pb_rails("body", props: { text: "Name", data: { async_user_name: true } }) %>
+    <%= pb_rails("detail", props: { text: "Title and Department", data: { async_user_detail: true } }) %>
+  <% end %>
+</template>
+
+<script>
+  (() => {
+    const dropdown = document.getElementById("async-rich-user-dropdown");
+    const template = document.getElementById("async-user-option-template");
+    if (!dropdown || !template || 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,company",
+      });
+
+      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) => {
+            const option = {
+              id: user.id,
+              label: `${user.firstName} ${user.lastName}`,
+              value: user.id,
+              title: user.company?.title || "",
+              department: user.company?.department || "",
+            };
+            const content = template.content.cloneNode(true);
+            content.querySelector("[data-async-user-name]").textContent = option.label;
+            content.querySelector("[data-async-user-detail]").textContent =
+              [option.title, option.department].filter(Boolean).join(" · ");
+            return { option, content };
+          }));
+        })
+        .catch(() => setError());
+    });
+  })();
+</script>

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

@@ -0,0 +1,10 @@
+For custom Rails result rows, pass `{ option, content }` entries to the async search event's `setResults` callback. Plain option objects and rich entries can appear in the same result array.
+
+- `option` is the ordinary serializable Dropdown option object: `id`, `label`, `value`, and any custom data. `disabled: true` prevents selection.
+- `content` is an `Element` or `DocumentFragment`, usually cloned from a Rails-rendered `<template>`. Dropdown clones it into its standard option wrapper; it does not consume or move your original nodes. Populate API text with `textContent`. HTML strings are not a rich-content input.
+
+The explicit `option.label` is used in the selected input, even when the row contains additional text. Content is not serialized into option data or the existing `pb:dropdown:selected` payload. Nested content supports click selection and keyboard navigation, including when the menu is portaled.
+
+Provide display content only: do not include another Dropdown option wrapper, interactive controls, or named form inputs in suggestions. Keep submitted fields outside the result content and update them from selection data. Cloning preserves markup and data attributes but does not copy JavaScript event listeners attached to the original nodes.
+
+The example searches [DummyJSON’s public sample users API](https://dummyjson.com/docs/users) without credentials or an API key. Try `Emily` or `Michael`. It renders Rails Body and Detail kits for the name, job title, and department, retaining title and department in the selected option data. The same pattern works with a User kit or other custom display content.

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

@@ -0,0 +1,42 @@
+<%= pb_rails("dropdown", props: {
+  id: "async-user-dropdown",
+  label: "User",
+  name: "async_user",
+  placeholder: "Try Emily or Michael",
+  autocomplete: true,
+  async: true,
+  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`. 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. 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; completed results and status messages remain available when reopening. 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.
+
+After clear, clicking an async autocomplete does not open an empty menu. The menu opens when a search starts or results/status content is available. An async search-bar menu can still 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/example.yml

@@ -2,6 +2,8 @@ examples:
   rails:
   - dropdown_default_rails: Default
   - dropdown_with_autocomplete: Autocomplete
+  - dropdown_async_search: Async Search
+  - dropdown_async_custom_content: Async Search with Custom Content
   - dropdown_multi_select_rails: Multi Select
   - dropdown_multi_select_with_autocomplete: Multi Select with Autocomplete
   - dropdown_multi_select_display_rails: Multi Select with Form Pill Props

data/app/pb_kits/playbook/pb_dropdown/dropdown.rb

@@ -27,6 +27,9 @@ module Playbook
                         default: true
       prop :autocomplete, type: Playbook::Props::Boolean,
                           default: false
+      prop :async, type: Playbook::Props::Boolean, default: false
+      prop :search_term_minimum_length, default: 3
+      prop :search_debounce_timeout, default: 250
       prop :searchbar, type: Playbook::Props::Boolean,
                        default: false
       prop :multi_select, type: Playbook::Props::Boolean,
@@ -71,6 +74,10 @@ module Playbook
       def data
         Hash(prop(:data)).merge(
           pb_dropdown: true,
+          pb_dropdown_async: async ? true : nil,
+          pb_dropdown_default_value: async && default_value.present? ? default_value.to_json : nil,
+          pb_dropdown_search_term_minimum_length: async ? search_term_minimum_length : nil,
+          pb_dropdown_search_debounce_timeout: async ? search_debounce_timeout : nil,
           pb_dropdown_multi_select: multi_select,
           pb_dropdown_disabled: disabled,
           pb_dropdown_variant: variant,