playbook_ui 14.19.0.pre.rc.2 → 14.20.0.pre.alpha.revert4453PBNTR933reactdraggablebugdragbtwnexamples7854

data/app/pb_kits/playbook/pb_draggable/docs/_draggable_drop_zones.html.erb

@@ -10,7 +10,13 @@
   { id: "63", text: "Task 3" }
 ] %>
 
-<%= pb_rails("flex", props: { justify: "around" }) do %>
+<% data_line = [
+  { id: "71", text: "Task 1" },
+  { id: "72", text: "Task 2" },
+  { id: "73", text: "Task 3" }
+] %>
+
+<%= pb_rails("flex", props: { justify: "between" }) do %>
   <%= pb_rails("flex/flex_item", props: { margin_right: "xl" }) do %>
     <%= pb_rails("draggable", props: { drop_zone_type: "shadow", initial_items: data_shadow }) do %>
       <%= pb_rails("caption", props: { margin_bottom: "xs", text: "Shadow", text_align: "center" }) %>
@@ -40,4 +46,19 @@
       <% end %>
     <% end %>
   <% end %>
+
+  <%= pb_rails("flex/flex_item", props: { margin_right: "xl" }) do %>
+    <%= pb_rails("draggable", props: { drop_zone_type: "line", initial_items: data_line }) do %>
+      <%= pb_rails("caption", props: { margin_bottom: "xs", text: "Line", text_align: "center" }) %>
+      <%= pb_rails("draggable/draggable_container", props: { drop_zone_direction: "vertical", html_options: { style: { width: "200px" } } }) do %>
+        <% data_line.each do |item| %>
+          <%= pb_rails("card", props: { drag_id: item[:id], draggable_item: true, margin_bottom: "xs", padding: "xs", padding_right: "xl", drop_zone_line_color: "primary" }) do %>
+            <%= pb_rails("flex", props: { align_items: "stretch", flex_direction: "column" }) do %>
+              <%= pb_rails("body", props: { text: item[:text] }) %>
+            <% end %>
+          <% end %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
 <% end %>

data/app/pb_kits/playbook/pb_draggable/docs/_draggable_drop_zones_line.html.erb

@@ -0,0 +1,55 @@
+<% initial_items = [
+  {
+    id: "211",
+    url: "https://unsplash.it/500/400/?image=633",
+  },
+  {
+    id: "212",
+    url: "https://unsplash.it/500/400/?image=634",
+  },
+  {
+    id: "213",
+    url: "https://unsplash.it/500/400/?image=637",
+  },
+] %>
+
+<% next_init_items = [
+  {
+    id: "2111",
+    url: "https://unsplash.it/500/400/?image=633",
+  },
+  {
+    id: "2112",
+    url: "https://unsplash.it/500/400/?image=634",
+  },
+  {
+    id: "2113",
+    url: "https://unsplash.it/500/400/?image=637",
+  },
+] %>
+
+<%= pb_rails("draggable", props: {initial_items: initial_items, drop_zone_type: "line"}) do %>
+  <%= pb_rails("draggable/draggable_container", props: { drop_zone_direction: "vertical" }) do %>
+    <%= pb_rails("flex", props: { gap: "sm", orientation: "column", height: "367px" }) do %>
+      <% initial_items.each do |item| %>
+        <%= pb_rails("draggable/draggable_item", props:{drag_id: item[:id], drop_zone_line_color: "purple"}) do %>
+          <%= pb_rails("image", props: { alt: item[:id], size: "md", url: item[:url] }) %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>
+
+<br/>
+
+<%= pb_rails("draggable", props: {initial_items: next_init_items, drop_zone_type: "line"}) do %>
+  <%= pb_rails("draggable/draggable_container", props: { drop_zone_direction: "horizontal" }) do %>
+    <%= pb_rails("flex", props: { gap: "sm", html_options: { style: "width: 332px;" } }) do %>
+      <% initial_items.each do |item| %>
+        <%= pb_rails("draggable/draggable_item", props:{drag_id: item[:id], drop_zone_line_color: "primary"}) do %>
+          <%= pb_rails("image", props: { alt: item[:id], size: "md", url: item[:url] }) %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/pb_kits/playbook/pb_draggable/docs/_draggable_drop_zones_line_rails.md

@@ -0,0 +1,5 @@
+When using the "line" style, make sure to set the appropriate `direction` attribute within the `drop_zone_direction` prop on the `draggable/draggable_container` component based on the orientation of your draggable view: "vertical" or "horizontal." Note that the direction attribute only applies to the "line" style and does not affect other drop zone styles. Also, set the `drop_zone_line_color` prop on the `draggable/draggable_item` component to "primary" or "purple".
+
+The length of the line is calculated based off of the width (for "vertical") or height (for "horizontal") of the parent container holding the draggable items. 
+
+Additionally, if the parent container of the `draggable`/`draggable/draggable_container` (or a subcontainer within) does not have a set height (for "vertical") or width (for "horizontal"), like the [Draggable Drop Zones doc example](https://playbook.powerapp.cloud/kits/draggable/rails#draggable-drop-zones) does, elements on the page may jump up (for "vertical") or to the left (for "horizontal") when an item is actively being dragged. To prevent this, give a parent element a fixed height (for "vertical") or width (for "horizontal") as demonstrated in this doc example.

data/app/pb_kits/playbook/pb_draggable/docs/_draggable_drop_zones_rails.md

@@ -0,0 +1,5 @@
+The Draggable kit lets you customize the style of drop zones that appear when dragging an item.
+
+By default, drop zones are in the "ghost" style, but you can also choose from "shadow," "outline," and "line."
+
+When using the "line" type, make sure to set the appropriate `direction` attribute on the `draggable/draggable_container` component based on the orientation of your draggable view: "vertical" or "horizontal." Note that the direction attribute only applies to the "line" type and does not affect other drop zone styles. For more on the "line" style in particular, check out the [Draggable Drop Zones Line doc example](https://playbook.powerapp.cloud/kits/draggable/rails#draggable-drop-zones-line).

data/app/pb_kits/playbook/pb_draggable/docs/_draggable_event_listeners.jsx

@@ -0,0 +1,59 @@
+import React, { useState } from "react";
+
+import Flex from '../../pb_flex/_flex'
+import Image from '../../pb_image/_image'
+import Draggable from '../../pb_draggable/_draggable'
+import { DraggableProvider } from '../../pb_draggable/context'
+
+const data = [
+  {
+    id: "100",
+    url: "https://unsplash.it/500/400/?image=638",
+  },
+  {
+    id: "200",
+    url: "https://unsplash.it/500/400/?image=639",
+  },
+  {
+    id: "300",
+    url: "https://unsplash.it/500/400/?image=640",
+  },
+];
+
+const DraggableDefault = (props) => {
+  const [initialState, setInitialState] = useState(data);
+
+  return (
+    <>
+    <DraggableProvider initialItems={data}
+        onReorder={(items) => setInitialState(items)}
+    >
+        <Draggable.Container {...props}>
+        <Flex>
+            {initialState.map(({ id, url }) => (
+              <Draggable.Item dragId={id} 
+                  key={id}
+                  onDrag={() => console.log(`${id} drag!`)}
+                  onDragEnd={() => console.log(`${id} drag end!`)}
+                  onDragEnter={() => console.log(`${id} drag enter!`)}
+                  onDragLeave={() => console.log(`${id} drag leave!`)}
+                  onDragOver={() => console.log(`${id} drag over!`)}
+                  onDragStart={() => console.log(`${id} drag start!`)}
+                  onDrop={() => console.log(`${id} drop!`)}
+              >
+                <Image alt={id} 
+                    margin="xs"
+                    size="md" 
+                    url={url} 
+                />
+              </Draggable.Item>
+            ))}
+         </Flex>
+        </Draggable.Container>
+    </DraggableProvider>
+    </>
+
+  );
+};
+
+export default DraggableDefault;

data/app/pb_kits/playbook/pb_draggable/docs/_draggable_event_listeners_react.md

@@ -0,0 +1 @@
+You can add drag event listeners for `onDrag`, `onDragEnd`, `onDragEnter`, `onDragLeave`, `onDragOver`, `onDragStart`, and `onDrop`.

data/app/pb_kits/playbook/pb_draggable/docs/example.yml

@@ -9,6 +9,7 @@ examples:
   - draggable_drop_zones: Draggable Drop Zones
   - draggable_drop_zones_colors: Draggable Drop Zones Colors
   - draggable_drop_zones_line: Draggable Drop Zones Line
+  - draggable_event_listeners: Draggable Event Listeners
 
   rails:
   - draggable_default: Default
@@ -19,4 +20,5 @@ examples:
   - draggable_multiple_containers: Dragging Across Multiple Containers
   - draggable_drop_zones: Draggable Drop Zones
   - draggable_drop_zones_colors: Draggable Drop Zones Colors
+  - draggable_drop_zones_line: Draggable Drop Zones Line
   - draggable_event_listeners: Draggable Event Listeners

data/app/pb_kits/playbook/pb_draggable/docs/index.js

@@ -6,4 +6,5 @@ export { default as DraggableMultipleContainers } from './_draggable_multiple_co
 export { default as DraggableWithTable } from './_draggable_with_table.jsx'
 export { default as DraggableDropZones } from './_draggable_drop_zones.jsx'
 export { default as DraggableDropZonesColors } from './_draggable_drop_zones_colors.jsx'
-export { default as DraggableDropZonesLine } from './_draggable_drop_zones_line.jsx'
+export { default as DraggableDropZonesLine } from './_draggable_drop_zones_line.jsx'
+export { default as DraggableEventListeners } from './_draggable_event_listeners.jsx'

data/app/pb_kits/playbook/pb_draggable/draggable_container.rb

@@ -7,13 +7,23 @@ module Playbook
                  default: "div"
       prop :container, type: Playbook::Props::String,
                        default: ""
+      prop :drop_zone_direction, type: Playbook::Props::Enum,
+                                 values: ["horizontal", "vertical", nil],
+                                 default: nil
 
       def data
         Hash(prop(:data)).merge(pb_draggable_container: true)
       end
 
       def classname
-        generate_classname("pb_draggable_container")
+        direction_class = case drop_zone_direction
+                          when "horizontal"
+                            "line_horizontal"
+                          when "vertical"
+                            "line_vertical"
+                          end
+
+        generate_classname("pb_draggable_container", direction_class, separator: " ")
       end
     end
   end

data/app/pb_kits/playbook/pb_draggable/draggable_item.rb

@@ -9,13 +9,23 @@ module Playbook
                  default: "div"
       prop :container, type: Playbook::Props::String,
                        default: ""
+      prop :drop_zone_line_color, type: Playbook::Props::Enum,
+                                  values: ["primary", "purple", nil],
+                                  default: nil
 
       def data
         Hash(prop(:data)).merge(pb_draggable_item: true)
       end
 
       def classname
-        generate_classname("pb_draggable_item")
+        line_color_class = case drop_zone_line_color
+                           when "primary"
+                             "drop_zone_color_primary"
+                           when "purple"
+                             "drop_zone_color_purple"
+                           end
+
+        generate_classname("pb_draggable_item", line_color_class, separator: " ")
       end
     end
   end

data/app/pb_kits/playbook/pb_draggable/index.js

@@ -2,7 +2,7 @@ import PbEnhancedElement from "../pb_enhanced_element";
 
 const DRAGGABLE_SELECTOR  = "[data-pb-draggable]";
 const DRAGGABLE_CONTAINER = ".pb_draggable_container";
-const NEEDS_CLONE         = ["shadow", "outline"];   // clone only for these types
+const NEEDS_CLONE         = ["shadow", "outline", "line"];   // clone only for these types
 
 export default class PbDraggable extends PbEnhancedElement {
   static get selector() { return DRAGGABLE_SELECTOR; }
@@ -116,7 +116,9 @@ export default class PbDraggable extends PbEnhancedElement {
       /* ---------------------------------------------------------------- */
     }
 
-    requestAnimationFrame(() => (event.target.style.opacity = "0.5"));
+    if (this.dragZoneType !== "line") {
+      requestAnimationFrame(() => (event.target.style.opacity = "0.5"));
+    }
   }
 
   /* ---------------- DRAG ENTER ---------------- */

data/app/pb_kits/playbook/pb_draggable/subcomponents/DraggableItem.tsx

@@ -8,6 +8,7 @@ import {
 } from "../../utilities/props";
 import { globalProps } from "../../utilities/globalProps";
 import { DraggableContext } from "../context";
+import { noop } from '../../utilities/object'
 
 type DraggableItemProps = {
   aria?: { [key: string]: string };
@@ -17,6 +18,13 @@ type DraggableItemProps = {
   data?: { [key: string]: string };
   htmlOptions?: {[key: string]: string | number | boolean | (() => void)},
   id?: string;
+  onDrag?: () => void,
+  onDragEnd?: () => void,
+  onDragEnter?: () => void,
+  onDragLeave?: () => void,
+  onDragOver?: () => void,
+  onDragStart?: () => void,
+  onDrop?: () => void,
   dragId?: string;
   tag?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'div' | 'tr' | 'th' | 'td' | 'thead' | 'col' | 'tbody',
 };
@@ -31,7 +39,14 @@ const DraggableItem = (props: DraggableItemProps) => {
     htmlOptions = {},
     id,
     dragId,
-    tag="div"
+    tag="div",
+    onDrag = noop,
+    onDragEnd = noop,
+    onDragEnter = noop,
+    onDragLeave = noop,
+    onDragOver = noop,
+    onDragStart = noop,
+    onDrop = noop,
   } = props;
 
   const {
@@ -61,7 +76,7 @@ const DraggableItem = (props: DraggableItemProps) => {
   );
 
   // Enhanced drag start handler that preserves dimensions
-  const onDragStart = (e: React.DragEvent) => {
+  const handleDragStartWithCustom = (e: React.DragEvent) => {
     if (dropZone !== 'ghost' && itemRef.current) {
       // Create a clone for the drag image
       const clone = itemRef.current.cloneNode(true) as HTMLElement;
@@ -96,6 +111,9 @@ const DraggableItem = (props: DraggableItemProps) => {
 
     // Call the original handler
     handleDragStart(dragId, container);
+
+    // Custom event handler
+    onDragStart()
   };
 
   return (
@@ -107,9 +125,19 @@ const DraggableItem = (props: DraggableItemProps) => {
         draggable
         id={id}
         key={dragId}
-        onDragEnd={() => handleDragEnd()}
-        onDragEnter={() => handleDragEnter(dragId, container)}
-        onDragStart={onDragStart}
+        onDrag={onDrag}
+        onDragEnd={() => {
+          handleDragEnd()
+          onDragEnd()
+        }}
+        onDragEnter={() => {
+          handleDragEnter(dragId, container)
+          onDragEnter()
+        }}
+        onDragLeave={onDragLeave}
+        onDragOver={onDragOver}
+        onDragStart={handleDragStartWithCustom}
+        onDrop={onDrop}
         ref={itemRef}
     >
       {children}

data/app/pb_kits/playbook/pb_dropdown/_dropdown.scss

@@ -15,7 +15,7 @@
       @include pb_body;
       border: 1px solid $border_light;
       background-color: $white;
-      height: 45px;
+      min-height: 45px;
       @media (hover: hover) {
         &:hover,
         &:active,
@@ -41,6 +41,11 @@
         outline: unset;
         transition: box-shadow 0.15s ease-in-out;
       }
+      &:focus-within {
+        box-shadow: 0px 0px 0 1px $primary !important;
+        outline: unset;
+        transition: box-shadow 0.15s ease-in-out;
+      }
 
       &[class*="_select_only"] {
         box-shadow: inset 0 -11px 20px rgba($primary, 0.05);

data/app/pb_kits/playbook/pb_dropdown/_dropdown.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useRef, useEffect, forwardRef, useImperativeHandle } from "react";
+import React, { useState, useRef, useEffect, forwardRef, useImperativeHandle, useMemo } from "react";
 import classnames from "classnames";
 import { buildAriaProps, buildCss, buildDataProps, buildHtmlProps } from "../utilities/props";
 import { globalProps } from "../utilities/globalProps";
@@ -25,6 +25,7 @@ type DropdownProps = {
     blankSelection?: string;
     children?: React.ReactChild[] | React.ReactChild | React.ReactElement[];
     className?: string;
+    formPillProps?: GenericObject;
     dark?: boolean;
     data?: { [key: string]: string };
     defaultValue?: GenericObject;
@@ -33,10 +34,10 @@ type DropdownProps = {
     id?: string;
     isClosed?: boolean;
     label?: string;
+    multiSelect?: boolean;
     onSelect?: (arg: GenericObject) => null;
     options: GenericObject;
     separators?: boolean;
-    triggerRef?: any;
     variant?: "default" | "subtle";
 };
 
@@ -62,10 +63,11 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         id,
         isClosed = true,
         label,
+        multiSelect = false,
+        formPillProps,
         onSelect,
         options,
         separators = true,
-        triggerRef,
         variant = "default",
     } = props;
 
@@ -82,7 +84,20 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
     const [isDropDownClosed, setIsDropDownClosed, toggleDropdown] = useDropdown(isClosed);
 
     const [filterItem, setFilterItem] = useState("");
-    const [selected, setSelected] = useState<GenericObject>(defaultValue);
+    const initialSelected = useMemo(() => {
+      if (multiSelect) {
+        if (Array.isArray(defaultValue)) return defaultValue;
+        return defaultValue && Object.keys(defaultValue).length
+          ? [defaultValue]
+          : [];
+      }
+      return defaultValue || {};
+    }, [multiSelect, defaultValue]);
+
+    const [selected, setSelected] = useState<GenericObject | GenericObject[]>(
+      initialSelected
+    );
+
     const [isInputFocused, setIsInputFocused] = useState(false);
     const [hasTriggerSubcomponent, setHasTriggerSubcomponent] = useState(true);
     const [hasContainerSubcomponent, setHasContainerSubcomponent] =
@@ -91,23 +106,21 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
     const [focusedOptionIndex, setFocusedOptionIndex] = useState(-1);
 
     const dropdownRef = useRef(null);
-    const inputRef = useRef(null);
+    const inputRef = useRef<HTMLInputElement>(null);
     const inputWrapperRef = useRef(null);
     const dropdownContainerRef = useRef(null);
 
+    const selectedArray = Array.isArray(selected)
+    ? selected
+    : selected && Object.keys(selected).length
+    ? [selected]
+    : [];
+
     const { trigger, container, otherChildren } =
         separateChildComponents(children);
 
     useEffect(() => {
-        // Set the parent element of the trigger to relative to allow for absolute positioning of the dropdown
-        //Only needed for when useDropdown hook used with external trigger
-        if (triggerRef?.current) {
-            const parentElement = triggerRef.current.parentNode;
-            if (parentElement) {
-                parentElement.style.position = 'relative';
-            }
-        }
-        // Handle clicks outside the dropdown
+     // Handle clicks outside the dropdown
         const handleClick = handleClickOutside({
             inputWrapperRef,
             dropdownContainerRef,
@@ -134,16 +147,23 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
 
     const blankSelectionOption: GenericObject = blankSelection ? [{ label: blankSelection, value: "" }] : [];
     const optionsWithBlankSelection = blankSelectionOption.concat(options);
-    const filteredOptions = optionsWithBlankSelection?.filter((option: GenericObject) => {
-        const label = typeof option.label === 'string' ? option.label.toLowerCase() : option.label;
-        return String(label).toLowerCase().includes(filterItem.toLowerCase());
-    });
+
+    const availableOptions = useMemo(()=> {
+        if (!multiSelect) return optionsWithBlankSelection;
+        return optionsWithBlankSelection.filter((option: GenericObject) => !selectedArray.some((sel) => sel.label === option.label));
+    }, [optionsWithBlankSelection, selectedArray, multiSelect]);
+    
+    const filteredOptions = useMemo(() => {
+          return availableOptions.filter((opt: GenericObject) =>
+            String(opt.label).toLowerCase().includes(filterItem.toLowerCase())
+          );
+        }, [availableOptions, filterItem]);
 
     // For keyboard accessibility: Set focus within dropdown to selected item if it exists
     useEffect(() => {
         if (!isDropDownClosed) {
             let newIndex = 0;
-            if (selected && selected?.label) {
+            if (selected && !Array.isArray(selected) && selected.label) {
                 const selectedIndex = filteredOptions.findIndex((option: GenericObject) => option.label === selected.label);
                 if (selectedIndex >= 0) {
                     newIndex = selectedIndex;
@@ -159,22 +179,42 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
         setIsDropDownClosed(false);
     };
 
-    const handleOptionClick = (selectedItem: GenericObject) => {
-        setSelected(selectedItem);
-        setFilterItem("");
-        setIsDropDownClosed(true);
-        onSelect && onSelect(selectedItem);
-    };
+
+      const handleOptionClick = (clickedItem: GenericObject) => {
+                if (multiSelect) {
+                    setSelected((prev) => {
+                       const list = prev as GenericObject[];
+                       const exists = list.find((option) => option.value === clickedItem.value);
+                       const next = exists
+                       ? list.filter((option) => option.value !== clickedItem.value)
+                           : [...list, clickedItem];
+                   onSelect && onSelect(next);
+                       return next;
+                   });
+                   setFilterItem("");
+                   setIsDropDownClosed(true);
+               } else {
+                   setSelected(clickedItem);
+                   setFilterItem("");
+                   setIsDropDownClosed(true);
+                   onSelect && onSelect(clickedItem);
+            }
+             };
 
     const handleWrapperClick = () => {
-        autocomplete && inputRef.current.focus();
+        autocomplete && inputRef?.current?.focus();
         toggleDropdown();
     };
 
     const handleBackspace = () => {
+      if (multiSelect) {
+        setSelected([]);
+        onSelect && onSelect([]);
+      } else {
         setSelected({});
         onSelect && onSelect(null);
         setFocusedOptionIndex(-1);
+      }
     };
 
     const componentsToRender = prepareSubcomponents({
@@ -188,12 +228,17 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
     });
 
     useImperativeHandle(ref, () => ({
-        clearSelected: () => {
-            setSelected({});
-            setFilterItem("");
-            setIsDropDownClosed(true);
-            onSelect && onSelect(null);
-        },
+      clearSelected: () => {
+        if (multiSelect) {
+          setSelected([]);
+          onSelect && onSelect([]);
+        } else {
+          setSelected({});
+          onSelect && onSelect(null);
+        }
+        setFilterItem("");
+        setIsDropDownClosed(true);
+      },
     }));
 
     return (
@@ -202,7 +247,7 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
             {...htmlProps}
             className={classes}
             id={id}
-            style={triggerRef ? { position: "absolute" } : { position: "relative" }}
+            style={{position: "relative"}}
         >
             <DropdownContext.Provider
                 value={{
@@ -211,6 +256,7 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
                     filteredOptions,
                     filterItem,
                     focusedOptionIndex,
+                    formPillProps,
                     handleBackspace,
                     handleChange,
                     handleOptionClick,
@@ -219,14 +265,15 @@ let Dropdown = (props: DropdownProps, ref: any): React.ReactElement | null => {
                     inputWrapperRef,
                     isDropDownClosed,
                     isInputFocused,
+                    multiSelect,
+                    onSelect,
                     optionsWithBlankSelection,
                     selected,
                     setFocusedOptionIndex,
                     setIsDropDownClosed,
                     setIsInputFocused,
                     setSelected,
-                    toggleDropdown,
-                    triggerRef
+                    toggleDropdown
                 }}
             >
                 {label &&

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

@@ -0,0 +1,31 @@
+<% 
+  options = [
+    { label: 'United States', value: 'United States', id: 'us' },
+    { label: 'Canada', value: 'Canada', id: 'ca' },
+    { label: 'Pakistan', value: 'Pakistan', id: 'pk' },
+  ]
+
+%>
+
+<% 
+  options2 = [
+    { label: 'India', value: 'India', id: 'in' },
+    { label: 'Mexico', value: 'Mexico', id: 'mx' },
+    { label: 'Brazil', value: 'Brazil', id: 'br' },
+    { label: 'Argentina', value: 'Argentina', id: 'ar' },
+    { label: 'Colombia', value: 'Colombia', id: 'co' },
+    { label: 'Chile', value: 'Chile', id: 'cl' },
+    { label: 'Peru', value: 'Peru', id: 'pe' },
+  ]
+
+%>
+
+<%= pb_rails("dropdown", props: {options: options}) %>
+
+<script>
+  document.addEventListener("pb:dropdown:selected", (e) => {
+    const option   = e.detail;
+    const dropdown = e.target;
+    console.log("Selected option:", option);
+})
+</script>

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

@@ -0,0 +1,5 @@
+This kit's `options` prop requires an array of objects, each of which will be used as the selectable options within the dropdown. Each option object can support any number of key-value pairs, but each MUST contain `label`, `value` and `id`. 
+
+The kit also comes with a custom event called "pb:dropdown:selected" which updates dynamically with the selection as it changes. See code snippet to see this in action.
+
+In addition, a data attribute called `data-option-selected` with the selection is also rendered on the parent dropdown div.

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

@@ -1,4 +1,4 @@
-<% 
+<%
   options = [
     { label: 'United States', value: 'United States', id: 'us' },
     { label: 'Canada', value: 'Canada', id: 'ca' },
@@ -6,4 +6,7 @@
   ]
 %>
 
-<%= pb_rails("dropdown", props: { error: "Please make a valid selection", options: options }) %>
+<%= pb_rails("dropdown", props: {
+  error: raw(pb_rails("icon", props: { icon: "warning" }) + " Please make a valid selection"),
+  options: options
+}) %>