playbook_ui 16.4.0.pre.rc.3 → 16.4.0.pre.rc.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae3803bd5b745bfb80cc3735185a84ad54261d66a835da1430b4a9e490e99a79
-  data.tar.gz: b43613542fe8f44fb33f03ceefb5e2420ad38e371e4489fc4085187cdcd12361
+  metadata.gz: ad1b7d3456e544a5d908b0fd556bc44c61607a27fdcebd55013054591ced1851
+  data.tar.gz: 65ed19c014844a0aceaa592e61f53018d09f2a835f05f58aa19c7f3805653ef5
 SHA512:
-  metadata.gz: 9d563bf3c9b4ce0829a5dca7747f5365507a24fa0bfeed2a6caaef00ab51f52aeae7df2664060159995d041bced0a521bd0c9fbf0b2bb907386d0e8071184988
-  data.tar.gz: ad84d871ff6f43acdf3da0898888ec99e6b173bc68c71334932dc3a59f938e3bac7f4023028727ca2e6462c5a607c02dc254c768e740d5c2b7f03862edbaffaa
+  metadata.gz: 24b3221a2717bf9263f089a7b11811e9999aea7c5868e999d4b87a07b8dc7ad6e0330b801a4ff8c9cdde55539e31b602718837895f00a4b989b8d3bcd047b28d
+  data.tar.gz: 41309667045531ef713db565a84257662f781309f23247a9f154c4e91ba05277b3d5e0d903c7ca7ada074af99250f58405eee8f1e504b61286406d5e13f0a7ac

data/app/pb_kits/playbook/pb_advanced_table/Hooks/useTableState.ts

@@ -12,6 +12,7 @@ import {
 import { GenericObject } from "../../types";
 import { createColumnHelper } from "@tanstack/react-table";
 import { createCellFunction } from "../Utilities/CellRendererUtils";
+import { getParentOnlySortedRowModel } from "../Utilities/RowModelUtils";
 
 interface UseTableStateProps {
   tableData: GenericObject[];
@@ -36,6 +37,7 @@ interface UseTableStateProps {
   columnVisibilityControl?: GenericObject;
   rowStyling?: GenericObject;
   inlineRowLoading?: boolean;
+  sortParentOnly?: boolean;
 }
 
 export function useTableState({
@@ -55,7 +57,8 @@ export function useTableState({
   columnVisibilityControl,
   pinnedRows,
   rowStyling,
-  inlineRowLoading = false
+  inlineRowLoading = false,
+  sortParentOnly = false
 }: UseTableStateProps) {
 
   // Create a local state for expanded and setExpanded if expandedControl not used
@@ -190,7 +193,7 @@ export function useTableState({
     getSubRows: (row: GenericObject) => row.children,
     getCoreRowModel: getCoreRowModel(),
     getExpandedRowModel: getExpandedRowModel(),
-    getSortedRowModel: getSortedRowModel(),
+    getSortedRowModel: sortParentOnly ? getParentOnlySortedRowModel() : getSortedRowModel(),
     enableSortingRemoval: enableSortingRemoval,
     sortDescFirst: true,
     onRowSelectionChange: setRowSelection,

data/app/pb_kits/playbook/pb_advanced_table/Utilities/RowModelUtils.ts

@@ -0,0 +1,100 @@
+// Returns a row model getter that sorts only depth-0 (parent) rows so children and grandchild rows keep their original order under each parent.
+
+import type { Table, Row, RowModel, RowData } from "@tanstack/react-table";
+
+export function getParentOnlySortedRowModel<TData extends RowData>(): (
+  table: Table<TData>
+) => () => RowModel<TData> {
+  return (table) => () => {
+    const sortingState = table.getState().sorting;
+    const rowModel = table.getPreSortedRowModel();
+
+    if (!rowModel.rows.length || !sortingState?.length) {
+      return rowModel;
+    }
+
+    const sortedFlatRows: Row<TData>[] = [];
+    const availableSorting = sortingState.filter((sort) =>
+      table.getColumn(sort.id)?.getCanSort()
+    );
+
+    const columnInfoById: Record<
+      string,
+      {
+        sortUndefined?: false | -1 | 1 | "first" | "last";
+        invertSorting?: boolean;
+        sortingFn: (rowA: Row<TData>, rowB: Row<TData>, columnId: string) => number;
+      }
+    > = {};
+
+    availableSorting.forEach((sortEntry) => {
+      const column = table.getColumn(sortEntry.id);
+      if (!column) return;
+      columnInfoById[sortEntry.id] = {
+        sortUndefined: column.columnDef.sortUndefined,
+        invertSorting: column.columnDef.invertSorting,
+        sortingFn: column.getSortingFn(),
+      };
+    });
+
+    const parentRows = rowModel.rows.map((row) => ({ ...row }));
+    parentRows.sort((rowA, rowB) => {
+      for (let i = 0; i < availableSorting.length; i += 1) {
+        const sortEntry = availableSorting[i]!;
+        const columnInfo = columnInfoById[sortEntry.id]!;
+        const sortUndefined = columnInfo.sortUndefined;
+        const isDesc = sortEntry?.desc ?? false;
+        let sortInt = 0;
+
+        if (sortUndefined) {
+          const aValue = rowA.getValue(sortEntry.id);
+          const bValue = rowB.getValue(sortEntry.id);
+          const aUndefined = aValue === undefined;
+          const bUndefined = bValue === undefined;
+          if (aUndefined || bUndefined) {
+            if (sortUndefined === "first") return aUndefined ? -1 : 1;
+            if (sortUndefined === "last") return aUndefined ? 1 : -1;
+            sortInt =
+              aUndefined && bUndefined
+                ? 0
+                : aUndefined
+                  ? sortUndefined
+                  : -sortUndefined;
+          }
+        }
+
+        if (sortInt === 0) {
+          sortInt = columnInfo.sortingFn(rowA, rowB, sortEntry.id);
+        }
+
+        if (sortInt !== 0) {
+          if (isDesc) sortInt *= -1;
+          if (columnInfo.invertSorting) sortInt *= -1;
+          return sortInt;
+        }
+      }
+      return rowA.index - rowB.index;
+    });
+
+    function flattenRowsInOrder(rows: Row<TData>[]): void {
+      rows.forEach((row) => {
+        sortedFlatRows.push(row);
+        if (row.subRows?.length) {
+          flattenRowsInOrder(row.subRows);
+        }
+      });
+    }
+    flattenRowsInOrder(parentRows);
+
+    const rowsById: Record<string, Row<TData>> = {};
+    sortedFlatRows.forEach((row) => {
+      rowsById[row.id] = row;
+    });
+
+    return {
+      rows: parentRows,
+      flatRows: sortedFlatRows,
+      rowsById,
+    };
+  };
+}

data/app/pb_kits/playbook/pb_advanced_table/_advanced_table.tsx

@@ -66,6 +66,7 @@ type AdvancedTableProps = {
   showActionsBar?: boolean,
   persistToggleExpansionButton?: boolean,
   sortControl?: GenericObject
+  sortParentOnly?: boolean
   tableData: GenericObject[]
   tableOptions?: GenericObject
   tableProps?: GenericObject
@@ -114,6 +115,7 @@ const AdvancedTable = (props: AdvancedTableProps) => {
     selectableRows,
     persistToggleExpansionButton = false,
     sortControl,
+    sortParentOnly = false,
     stickyLeftColumn,
     tableData,
     tableOptions,
@@ -159,7 +161,8 @@ const AdvancedTable = (props: AdvancedTableProps) => {
     columnVisibilityControl,
     pinnedRows,
     rowStyling,
-    inlineRowLoading
+    inlineRowLoading,
+    sortParentOnly
   });
 
   // Initialize table actions

data/app/pb_kits/playbook/pb_advanced_table/advanced_table.test.jsx

@@ -495,7 +495,41 @@ test("sort button exists and sorts column data", () => {
 
   const row2 = kit.getElementsByTagName('tr')[2]
   expect(row2.id).toBe("0-0-0-row")
-}) 
+})
+
+test("sortParentOnly sorts only parent rows and keeps children grouped under parent", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        sortParentOnly
+        tableData={MOCK_DATA}
+    >
+      <AdvancedTable.Header enableSorting />
+      <AdvancedTable.Body />
+    </AdvancedTable>
+  )
+
+  const kit = screen.getByTestId(testId)
+  const sortButton = kit.querySelector(".header-sort-button.pb_th_link")
+  expect(sortButton).toBeInTheDocument()
+
+  const tbody = kit.querySelector('tbody')
+  const rowsBefore = tbody.getElementsByTagName('tr')
+  expect(rowsBefore[0]).toHaveTextContent('2021')
+
+  sortButton.click()
+
+  const rowsAfter = tbody.getElementsByTagName('tr')
+  expect(rowsAfter[0]).toHaveTextContent('2022')
+
+  const expandButton = kit.querySelector(".gray-icon.expand-toggle-icon")
+  expandButton.click()
+
+  const rowsExpanded = tbody.getElementsByTagName('tr')
+  expect(rowsExpanded.length).toBeGreaterThan(1)
+  expect(rowsExpanded[1]).toHaveTextContent('Q1')
+})
 
 test("Generates Table.Header default + custom classname", () => {
   render(

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sort_parent_only.jsx

@@ -0,0 +1,175 @@
+import React from "react"
+import AdvancedTable from '../../pb_advanced_table/_advanced_table'
+import MOCK_DATA from "./advanced_table_mock_data.json"
+
+import Caption from "../../pb_caption/_caption"
+
+const sharedColumnDefinitions = [
+  {
+    accessor: "year",
+    label: "Year",
+    cellAccessors: ["quarter", "month", "day"],
+  },
+  {
+    accessor: "newEnrollments",
+    label: "New Enrollments",
+  },
+  {
+    accessor: "scheduledMeetings",
+    label: "Scheduled Meetings",
+  },
+  {
+    accessor: "attendanceRate",
+    label: "Attendance Rate",
+  },
+  {
+    accessor: "completedClasses",
+    label: "Completed Classes",
+  },
+  {
+    accessor: "classCompletionRate",
+    label: "Class Completion Rate",
+  },
+  {
+    accessor: "graduatedStudents",
+    label: "Graduated Students",
+  },
+]
+
+const sortByColumnDefinitions = [
+  {
+    accessor: "year",
+    label: "Year",
+    cellAccessors: ["quarter", "month", "day"],
+  },
+  {
+    accessor: "newEnrollments",
+    label: "New Enrollments",
+    enableSort: true,
+  },
+  {
+    accessor: "scheduledMeetings",
+    label: "Scheduled Meetings",
+  },
+  {
+    accessor: "attendanceRate",
+    label: "Attendance Rate",
+    enableSort: true,
+  },
+  {
+    accessor: "completedClasses",
+    label: "Completed Classes",
+  },
+  {
+    accessor: "classCompletionRate",
+    label: "Class Completion Rate",
+  },
+  {
+    accessor: "graduatedStudents",
+    label: "Graduated Students",
+  },
+]
+
+const sortByColumnMultiDefinitions = [
+  {
+    accessor: "year",
+    label: "Year",
+    cellAccessors: ["quarter", "month", "day"],
+  },
+  {
+    label: "Enrollment Data",
+    columns: [
+      {
+        label: "Enrollment Stats",
+        columns: [
+          {
+            accessor: "newEnrollments",
+            label: "New Enrollments",
+            enableSort: true,
+          },
+          {
+            accessor: "scheduledMeetings",
+            label: "Scheduled Meetings",
+          },
+        ],
+      },
+    ],
+  },
+  {
+    label: "Performance Data",
+    columns: [
+      {
+        label: "Completion Metrics",
+        columns: [
+          {
+            accessor: "completedClasses",
+            label: "Completed Classes",
+            enableSort: true,
+          },
+          {
+            accessor: "classCompletionRate",
+            label: "Class Completion Rate",
+          },
+        ],
+      },
+      {
+        label: "Attendance",
+        columns: [
+          {
+            accessor: "attendanceRate",
+            label: "Attendance Rate",
+          },
+          {
+            accessor: "scheduledMeetings",
+            label: "Scheduled Meetings",
+          },
+        ],
+      },
+    ],
+  },
+]
+
+const AdvancedTableSortParentOnly = (props) => {
+  return (
+    <div>
+      <Caption text="Enable Sorting (first column) + sortParentOnly" />
+      <AdvancedTable
+          columnDefinitions={sharedColumnDefinitions}
+          sortParentOnly
+          tableData={MOCK_DATA}
+          {...props}
+      >
+        <AdvancedTable.Header enableSorting />
+        <AdvancedTable.Body />
+      </AdvancedTable>
+      <Caption marginTop="md" 
+          text="Sort by column + sortParentOnly"
+      />
+      <AdvancedTable
+          columnDefinitions={sortByColumnDefinitions}
+          enableSortingRemoval
+          sortParentOnly
+          tableData={MOCK_DATA}
+          {...props}
+      >
+        <AdvancedTable.Header />
+        <AdvancedTable.Body />
+      </AdvancedTable>
+      <Caption marginTop="md" 
+          text="Sort by column (multi-column) + sortParentOnly"
+      />
+      <AdvancedTable
+          columnDefinitions={sortByColumnMultiDefinitions}
+          enableSortingRemoval
+          sortParentOnly
+          tableData={MOCK_DATA}
+          {...props}
+      >
+        <AdvancedTable.Header enableSorting />
+        <AdvancedTable.Body />
+      </AdvancedTable>
+    </div>
+  )
+}
+
+export default AdvancedTableSortParentOnly

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sort_parent_only.md

@@ -0,0 +1,5 @@
+The `sortParentOnly` prop is a boolean set to `false` by default. When set to `true`, only parent (depth-0) rows are re-ordered when sorting; children and grandchildren stay grouped under their parent and keep their original order.
+
+`sortParentOnly` works with every sorting mode: `enableSorting` on the header, per-column `enableSort: true`, and sortable leaf columns in the multi-header variant. Sort indicators behave as usual.
+
+When omitted or `false`, sorting applies to all levels.

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

@@ -39,6 +39,7 @@ examples:
   - advanced_table_sort_per_column: Enable Sort By Column
   - advanced_table_sort_per_column_for_multi_column: Enable Sort By Column (Multi-Column)
   - advanced_table_custom_sort: Custom Sort
+  - advanced_table_sort_parent_only: Sort Parent Only
   - advanced_table_expanded_control: Expanded Control
   - advanced_table_expand_by_depth: Expand by Depth
   - advanced_table_subrow_headers: SubRow Headers

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

@@ -49,4 +49,5 @@ export { default as AdvancedTablePaddingControlPerRow } from './_advanced_table_
 export { default as AdvancedTableColumnStylingBackground } from './_advanced_table_column_styling_background.jsx'
 export { default as AdvancedTableColumnStylingBackgroundMulti } from './_advanced_table_column_styling_background_multi.jsx'
 export { default as AdvancedTableColumnStylingBackgroundCustom } from './_advanced_table_column_styling_background_custom.jsx'
-export { default as AdvancedTableCascadeCollapse } from './_advanced_table_cascade_collapse.jsx'
+export { default as AdvancedTableCascadeCollapse } from './_advanced_table_cascade_collapse.jsx'
+export { default as AdvancedTableSortParentOnly } from './_advanced_table_sort_parent_only.jsx'

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

@@ -0,0 +1,224 @@
+<%
+  default_options = [
+    { label: 'United States', value: 'unitedStates', id: 'us' },
+    { label: 'Canada', value: 'canada', id: 'ca' },
+    { label: 'Pakistan', value: 'pakistan', id: 'pk' },
+    { label: 'India', value: 'India', id: 'in' },
+    { label: 'Mexico', value: 'Mexico', id: 'mx' },
+  ]
+
+  multi_options = [
+    { label: 'United States', value: 'unitedStates', id: 'us' },
+    { label: 'Canada', value: 'canada', id: 'ca' },
+    { label: 'Pakistan', value: 'pakistan', id: 'pk' },
+    { label: 'India', value: 'india', id: 'in' },
+    { label: 'United Kingdom', value: 'unitedKingdom', id: 'uk' },
+  ]
+
+  autocomplete_options = [
+    { label: "United States", value: "unitedStates", areaCode: "+1", icon: "🇺🇸", id: "us" },
+    { label: "United Kingdom", value: "unitedKingdom", areaCode: "+44", icon: "🇬🇧", id: "gb" },
+    { label: "Pakistan", value: "pakistan", areaCode: "+92", icon: "🇵🇰", id: "pk" },
+  ]
+
+  custom_display_options = [
+    { label: "Strong Bad", value: "strongBad", id: "strong-bad", status: "Offline" },
+    { label: "Strong Mad", value: "strongMad", id: "strong-mad", status: "Online" },
+    { label: "Strong Sad", value: "strongSad", id: "strong-sad", status: "Away" },
+  ]
+
+  custom_display_content = capture do
+    pb_rails("flex", props: { align: "center" }) do
+      concat(pb_rails("avatar", props: { name: "", size: "xs", id: "cet-dropdown-avatar" }))
+      concat(pb_rails("body", props: { text: "", size: "xs", margin_x: "xs", id: "cet-dropdown-avatar-name" }))
+      concat(pb_rails("badge", props: { text: "", id: "cet-dropdown-avatar-status" }))
+    end
+  end
+%>
+
+<!-- Example 1: Default dropdown -->
+<%= pb_rails("dropdown", props: {
+  custom_event_type: "form:submitted,pb:dropdown:clearRequest",
+  id: "dropdown-default-cet",
+  label: "Default dropdown",
+  margin_bottom: "sm",
+  options: default_options,
+}) %>
+<%= pb_rails("flex", props: { wrap: true, gap: "sm", align: "center", margin_bottom: "md" }) do %>
+  <%= pb_rails("button", props: { id: "clear-default-cet", text: "Clear", variant: "primary" }) %>
+  <%= pb_rails("button", props: { id: "select-default-cet", text: "Select Canada", variant: "secondary" }) %>
+  <%= pb_rails("button", props: { id: "simulate-default-cet", text: "Simulate form submit", variant: "secondary" }) %>
+<% end %>
+
+<script>
+  (function() {
+    var id = "dropdown-default-cet";
+    document.getElementById("clear-default-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:clearRequest", { detail: { dropdownId: id } }));
+    });
+    document.getElementById("select-default-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:select", { detail: { dropdownId: id, optionId: "ca" } }));
+    });
+    document.getElementById("simulate-default-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("form:submitted", { detail: { dropdownId: id } }));
+    });
+  })();
+</script>
+
+<!-- Example 2: Multi select -->
+<%= pb_rails("dropdown", props: {
+  custom_event_type: "form:submitted,pb:dropdown:clearRequest",
+  id: "dropdown-multi-cet",
+  label: "Multi select dropdown",
+  margin_bottom: "sm",
+  multi_select: true,
+  options: multi_options,
+}) %>
+<%= pb_rails("flex", props: { wrap: true, gap: "sm", align: "center", margin_bottom: "md" }) do %>
+  <%= pb_rails("button", props: { id: "clear-multi-cet", text: "Clear", variant: "primary" }) %>
+  <%= pb_rails("button", props: { id: "select-multi-cet", text: "Select US + UK", variant: "secondary" }) %>
+  <%= pb_rails("button", props: { id: "simulate-multi-cet", text: "Simulate form submit", variant: "secondary" }) %>
+<% end %>
+
+<script>
+  (function() {
+    var id = "dropdown-multi-cet";
+    document.getElementById("clear-multi-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:clearRequest", { detail: { dropdownId: id } }));
+    });
+    document.getElementById("select-multi-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:select", { detail: { dropdownId: id, optionIds: ["us", "uk"] } }));
+    });
+    document.getElementById("simulate-multi-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("form:submitted", { detail: { dropdownId: id } }));
+    });
+  })();
+</script>
+
+<!-- Example 3: Autocomplete -->
+<%= pb_rails("dropdown", props: {
+  autocomplete: true,
+  custom_event_type: "form:submitted,pb:dropdown:clearRequest",
+  id: "dropdown-autocomplete-cet",
+  label: "Autocomplete dropdown",
+  margin_bottom: "sm",
+  options: autocomplete_options,
+}) %>
+<%= pb_rails("flex", props: { wrap: true, gap: "sm", align: "center", margin_bottom: "md" }) do %>
+  <%= pb_rails("button", props: { id: "clear-autocomplete-cet", text: "Clear", variant: "primary" }) %>
+  <%= pb_rails("button", props: { id: "select-autocomplete-cet", text: "Select Pakistan", variant: "secondary" }) %>
+  <%= pb_rails("button", props: { id: "simulate-autocomplete-cet", text: "Simulate form submit", variant: "secondary" }) %>
+<% end %>
+
+<script>
+  (function() {
+    var id = "dropdown-autocomplete-cet";
+    document.getElementById("clear-autocomplete-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:clearRequest", { detail: { dropdownId: id } }));
+    });
+    document.getElementById("select-autocomplete-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:select", { detail: { dropdownId: id, optionId: "pk" } }));
+    });
+    document.getElementById("simulate-autocomplete-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("form:submitted", { detail: { dropdownId: id } }));
+    });
+  })();
+</script>
+
+<!-- Example 4: Quick pick (Date Range) -->
+<%= pb_rails("dropdown", props: {
+  custom_event_type: "form:submitted,pb:dropdown:clearRequest",
+  id: "dropdown-quickpick-cet",
+  label: "Quickpick dropdown",
+  margin_bottom: "sm",
+  variant: "quickpick",
+}) %>
+<%= pb_rails("flex", props: { wrap: true, gap: "sm", align: "center", margin_bottom: "md" }) do %>
+  <%= pb_rails("button", props: { id: "clear-quickpick-cet", text: "Clear", variant: "primary" }) %>
+  <%= pb_rails("button", props: { id: "select-quickpick-cet", text: "Select This Week", variant: "secondary" }) %>
+  <%= pb_rails("button", props: { id: "simulate-quickpick-cet", text: "Simulate form submit", variant: "secondary" }) %>
+<% end %>
+
+<script>
+  (function() {
+    var id = "dropdown-quickpick-cet";
+    document.getElementById("clear-quickpick-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:clearRequest", { detail: { dropdownId: id } }));
+    });
+    document.getElementById("select-quickpick-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:select", { detail: { dropdownId: id, optionId: "quickpick-this-week" } }));
+    });
+    document.getElementById("simulate-quickpick-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("form:submitted", { detail: { dropdownId: id } }));
+    });
+  })();
+</script>
+
+<!-- Example 5: Custom display -->
+<%= pb_rails("dropdown", props: {
+  custom_event_type: "form:submitted,pb:dropdown:clearRequest",
+  id: "dropdown-custom-display-cet",
+  label: "Custom display (Subcomponent) dropdown",
+  margin_bottom: "sm",
+  options: custom_display_options,
+}) do %>
+  <%= pb_rails("dropdown/dropdown_trigger", props: { placeholder: "Select a User", custom_display: custom_display_content }) %>
+  <%= pb_rails("dropdown/dropdown_container") do %>
+    <% custom_display_options.each do |option| %>
+      <%= pb_rails("dropdown/dropdown_option", props: { option: option }) do %>
+        <%= pb_rails("flex", props: { align: "center", justify: "between" }) do %>
+          <%= pb_rails("flex/flex_item") do %>
+            <%= pb_rails("user", props: { name: option[:label], align: "left", avatar: true, orientation: "horizontal" }) %>
+          <% end %>
+          <%= pb_rails("flex/flex_item") do %>
+            <%= pb_rails("badge", props: { rounded: true, dark: true, text: option[:status], variant: option[:status] == "Offline" ? "neutral" : option[:status] == "Online" ? "success" : "warning" }) %>
+          <% end %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>
+<%= pb_rails("flex", props: { wrap: true, gap: "sm", align: "center", margin_bottom: "md" }) do %>
+  <%= pb_rails("button", props: { id: "clear-custom-display-cet", text: "Clear", variant: "primary" }) %>
+  <%= pb_rails("button", props: { id: "select-custom-display-cet", text: "Select Strong Sad", variant: "secondary" }) %>
+  <%= pb_rails("button", props: { id: "simulate-custom-display-cet", text: "Simulate form submit", variant: "secondary" }) %>
+<% end %>
+
+<script>
+  (function() {
+    var id = "dropdown-custom-display-cet";
+    document.getElementById("clear-custom-display-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:clearRequest", { detail: { dropdownId: id } }));
+    });
+    document.getElementById("select-custom-display-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("pb:dropdown:select", { detail: { dropdownId: id, optionId: "strong-sad" } }));
+    });
+    document.getElementById("simulate-custom-display-cet").addEventListener("click", function() {
+      document.dispatchEvent(new CustomEvent("form:submitted", { detail: { dropdownId: id } }));
+    });
+
+    document.addEventListener("pb:dropdown:selected", function(e) {
+      if (e.target && e.target.id === id && e.detail) {
+        var display = e.target.querySelector("[data-dropdown-trigger-custom-display]");
+        if (!display) return;
+        var nameEl = display.querySelector("#cet-dropdown-avatar-name");
+        if (nameEl) nameEl.textContent = e.detail.label;
+        var avatarEl = display.querySelector("#cet-dropdown-avatar");
+        if (avatarEl) {
+          var wrapper = avatarEl.querySelector(".avatar_wrapper");
+          if (wrapper) {
+            var initials = (e.detail.label[0] + (e.detail.label.split(" ").pop() || "")[0]).toUpperCase();
+            wrapper.dataset.name = e.detail.label;
+            wrapper.setAttribute("data-initials", initials);
+          }
+        }
+        var badgeEl = display.querySelector("#cet-dropdown-avatar-status");
+        if (badgeEl && e.detail.status) {
+          var variant = e.detail.status === "Online" ? "success" : e.detail.status === "Offline" ? "neutral" : "warning";
+          badgeEl.querySelector("span").textContent = e.detail.status;
+          badgeEl.className = "pb_badge_kit_" + variant;
+        }
+      }
+    });
+  })();
+</script>

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

@@ -0,0 +1,7 @@
+The `custom_event_type` prop lets the dropdown clear when specific events are dispatched. Set it to a comma-separated list of event names (e.g. Turbo or app-specific); when any of those events fire with optional `detail: { dropdownId }`, the matching dropdown clears. You can also listen for selection changes (`pb:dropdown:selected`), clear by dispatching `pb:dropdown:clear`, or set the selection by dispatching `pb:dropdown:select` with `detail: { dropdownId, optionId }` (or `optionIds` for multi-select).
+
+The examples show five distinct variants (default, multi select, autocomplete, quick pick, custom display). In each example, the first button clears the dropdown by dispatching a custom event that the dropdown listens for via `custom_event_type`. The second button sets the selection by dispatching `pb:dropdown:select`. The third button simulates a form submit by dispatching another custom event in `custom_event_type`, so the dropdown clears as it would after a real form submission.
+
+Turbo events (e.g. `turbo:frame-load`, `turbo:frame-render`, `turbo:submit-end`) often fire for many actions or across the page, so using them as `custom_event_type` can clear the dropdown more often than intended. Use them when that scope is what you want; otherwise use app-specific event names and dispatch with `detail: { dropdownId }` when the action happens, or dispatch `pb:dropdown:clear` from your own handler.
+
+Dropdowns with subcomponent structures that show custom displays (e.g. custom trigger or custom display) require a `pb:dropdown:selected` listener to update the visible UI from `event.detail` when a selection is made; clear is handled by the kit.

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

@@ -33,6 +33,7 @@ examples:
   - dropdown_quickpick_with_date_pickers_rails: Quick Pick with Date Pickers
   - dropdown_quickpick_with_date_pickers_default_rails: Quick Pick with Date Pickers (Default Value)
   - dropdown_required_indicator: Required Indicator
+  - dropdown_custom_event_type: Custom Event Type
 
   react:
   - dropdown_default: Default