playbook_ui 16.3.0 → 16.4.0.pre.alpha.PLAY2864circleiconbuttonloadingalignrails15138

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

@@ -0,0 +1,7 @@
+Use the `pinned_rows` prop to pin specific rows to the top of an Advanced Table. Pinned rows will remain at the top when scrolling through table data and will not change position if sorting is used.
+
+**NOTE:**
+- Sticky header required: Pinned rows must be used with `sticky: true` via `table_props` (works with both responsive and non-responsive tables)
+- Row ids required: Each object within the `table_data` array must contain a unique `id` in order to attach an id to all Rows for this to function.
+- `pinned_rows` takes a hash with a `top` key containing an array of row ids, as shown in the code snippet below.
+- For expandable rows, use the parent id in `pinned_rows[:top]`; all its children will automatically be pinned with it. If a child id is passed without the parent being pinned, nothing will be pinned.

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

@@ -7,6 +7,7 @@ examples:
   - advanced_table_table_props: Table Props
   - advanced_table_sticky_header_rails: Sticky Header
   - advanced_table_table_props_sticky_header: Sticky Header for Responsive Table
+  - advanced_table_pinned_rows_rails: Pinned Rows
   - advanced_table_beta_sort: Enable Sorting
   - advanced_table_responsive: Responsive Tables
   - advanced_table_custom_cell_rails: Custom Components for Cells
@@ -39,9 +40,11 @@ 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
+  - advanced_table_cascade_collapse: Cascade Collapse
   - advanced_table_collapsible_trail: Collapsible Trail
   - advanced_table_table_options: Table Options
   - advanced_table_table_props: Table Props

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

@@ -48,4 +48,6 @@ export { default as AdvancedTablePaddingControl } from './_advanced_table_paddin
 export { default as AdvancedTablePaddingControlPerRow } from './_advanced_table_padding_control_per_row.jsx'
 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 AdvancedTableColumnStylingBackgroundCustom } from './_advanced_table_column_styling_background_custom.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_advanced_table/index.js

@@ -1,5 +1,6 @@
 import PbEnhancedElement from "../pb_enhanced_element";
 import { updateSelectionActionBar } from "./advanced_table_action_bar";
+import { setArrowVisibility, toggleVisibility } from "../utilities/domHelpers";
 
 const ADVANCED_TABLE_SELECTOR = "[data-advanced-table]";
 const DOWN_ARROW_SELECTOR = "#advanced-table_open_icon";
@@ -20,10 +21,18 @@ export default class PbAdvancedTable extends PbEnhancedElement {
     this.childRowsMap = new Map();
   }
 
+  get table() {
+    return this.cachedTable || (this.cachedTable = this.element.closest("table"));
+  }
+
+  get mainTable() {
+    return this.cachedMainTable || (this.cachedMainTable = this.element.closest(".pb_advanced_table"));
+  }
+
   // Fetch and cache child rows for a given parent row ID
   childRowsFor(parentId) {
     if (!this.childRowsMap.has(parentId)) {
-      const table = this.element.closest("table");
+      const table = this.table;
       const rows = Array.from(
         table.querySelectorAll(`tr[data-row-parent="${parentId}"]`)
       );
@@ -33,7 +42,8 @@ export default class PbAdvancedTable extends PbEnhancedElement {
   }
 
   updateTableSelectedRowsAttribute() {
-    const mainTable = this.element.closest(".pb_advanced_table");
+    const mainTable = this.mainTable;
+    if (!mainTable) return;
     mainTable.dataset.selectedRows = JSON.stringify(
       Array.from(PbAdvancedTable.selectedRows)
     );
@@ -41,7 +51,8 @@ export default class PbAdvancedTable extends PbEnhancedElement {
 
   // Recalculate selected count based on all checked checkboxes
   recalculateSelectedCount() {
-    const table = this.element.closest("table");
+    const table = this.table;
+    if (!table) return;
     
     // Get all checkboxes that could be part of the selection
     // This includes row checkboxes and any parent checkboxes that might be programmatically checked
@@ -95,7 +106,7 @@ export default class PbAdvancedTable extends PbEnhancedElement {
     });
     
     this.updateTableSelectedRowsAttribute();
-    updateSelectionActionBar(table.closest(".pb_advanced_table"), PbAdvancedTable.selectedRows.size);
+    updateSelectionActionBar(this.mainTable, PbAdvancedTable.selectedRows.size);
     
     // Sync header select-all state
     if (selectAllCheckbox) {
@@ -139,7 +150,7 @@ export default class PbAdvancedTable extends PbEnhancedElement {
 
     this.updateTableSelectedRowsAttribute();
 
-    const table = checkbox.closest("table");
+    const table = this.table;
     const selectAllCheckbox = table.querySelector("#select-all-rows");
 
     if (selectAllCheckbox) {
@@ -153,7 +164,7 @@ export default class PbAdvancedTable extends PbEnhancedElement {
       );
       selectAllInput.checked = allChecked;
     }
-    updateSelectionActionBar(table.closest(".pb_advanced_table"), PbAdvancedTable.selectedRows.size);
+    updateSelectionActionBar(this.mainTable, PbAdvancedTable.selectedRows.size);
   }
 
   get target() {
@@ -161,10 +172,11 @@ export default class PbAdvancedTable extends PbEnhancedElement {
   }
 
   connect() {
-    const table = this.element.closest("table");
+    const table = this.table;
+    if (!table) return;
 
     this.hideCloseIcon();
-    const mainTable = this.element.closest(".pb_advanced_table");
+    const mainTable = this.mainTable;
     
     // This so it is hidden on first render
     if (mainTable) {
@@ -184,6 +196,17 @@ export default class PbAdvancedTable extends PbEnhancedElement {
     if (table.dataset.pbAdvancedTableInitialized) return;
     table.dataset.pbAdvancedTableInitialized = "true";
 
+    // Measure header height so pinned rows don't overlap when header wraps (e.g. mobile)
+    if (mainTable) {
+      PbAdvancedTable.updateStickyHeaderRowHeights(mainTable);
+      const resizeObserver = new ResizeObserver(() => {
+        PbAdvancedTable.updateStickyHeaderRowHeights(mainTable);
+        PbAdvancedTable.updatePinnedRowsStickyTops(mainTable);
+      });
+      resizeObserver.observe(table);
+      mainTable._advancedTableHeaderResizeObserver = resizeObserver;
+    }
+
     // Delegate checkbox changes
     table.addEventListener("change", (event) => {
       const checkbox = event.target.closest('input[type="checkbox"]');
@@ -271,9 +294,7 @@ export default class PbAdvancedTable extends PbEnhancedElement {
       }
 
       // Find direct child rows
-      const childRows = Array.from(
-        table.querySelectorAll(`[data-row-parent="${toggleBtn.id}"]`)
-      );
+      const childRows = this.childRowsFor(toggleBtn.id);
       this.toggleElement(childRows);
 
       // Restore original element context
@@ -284,7 +305,8 @@ export default class PbAdvancedTable extends PbEnhancedElement {
   }
 
   addBorderRadiusOnLastVisibleRow() {
-    const parentElement = this.element.closest(".pb_advanced_table");
+    const parentElement = this.mainTable;
+    if (!parentElement) return;
 
     const table = document.getElementById(parentElement.id);
 
@@ -304,9 +326,64 @@ export default class PbAdvancedTable extends PbEnhancedElement {
         lastVisibleRow.classList.add("last-visible-row");
         lastVisibleRow.classList.add("last-row-cell");
       }
+
+      PbAdvancedTable.updateStickyHeaderRowHeights(parentElement);
+      PbAdvancedTable.updatePinnedRowsStickyTops(table);
     }
   }
 
+  /**
+   * Measure thead height and set --advanced-table-header-height so pinned rows and
+   * multi-row sticky headers use the correct offset. Re-run when header wraps (e.g. mobile).
+   */
+  static updateStickyHeaderRowHeights(advancedTableWrapper) {
+    if (!advancedTableWrapper) return;
+    const table = advancedTableWrapper.querySelector("table.pb_table");
+    const thead = table?.querySelector("thead");
+    if (!thead) return;
+
+    const rows = Array.from(thead.querySelectorAll("tr"));
+    let totalHeight = 0;
+    rows.forEach((tr, index) => {
+      const h = tr.offsetHeight;
+      if (index === 0) {
+        advancedTableWrapper.style.setProperty(
+          "--advanced-table-header-row-0-height",
+          `${h}px`
+        );
+      } else if (index === 1) {
+        advancedTableWrapper.style.setProperty(
+          "--advanced-table-header-row-1-height",
+          `${h}px`
+        );
+      }
+      totalHeight += h;
+    });
+    advancedTableWrapper.style.setProperty(
+      "--advanced-table-header-height",
+      `${totalHeight}px`
+    );
+  }
+
+  /**
+   * Recompute sticky top for visible pinned rows so collapsed rows don't leave a gap.
+   * Call after expand/collapse and on load.
+   */
+  static updatePinnedRowsStickyTops(advancedTableWrapper) {
+    const pinnedTbody = advancedTableWrapper?.querySelector("tbody.pinned-rows-tbody");
+    if (!pinnedTbody) return;
+
+    const pinnedRows = Array.from(pinnedTbody.querySelectorAll("tr.pinned-row"));
+    const visibleRows = pinnedRows.filter(
+      (tr) => tr.style.display !== "none" && tr.offsetParent !== null
+    );
+
+    const headerOffset = "var(--advanced-table-header-height, 44px)";
+    visibleRows.forEach((tr, index) => {
+      tr.style.top = `calc(${headerOffset} + 2.5em * ${index})`;
+    });
+  }
+
   hideCloseIcon() {
     const closeIcon = this.element.querySelector(UP_ARROW_SELECTOR);
     closeIcon.style.display = "none";
@@ -316,11 +393,9 @@ export default class PbAdvancedTable extends PbEnhancedElement {
     elements.forEach((elem) => {
       elem.style.display = "table-row";
       elem.classList.add("is-visible");
-      const childRowsAll = this.element
-        .closest("table")
-        .querySelectorAll(
-          `[data-advanced-table-content^="${elem.dataset.advancedTableContent}-"]`
-        );
+      const childRowsAll = this.table.querySelectorAll(
+        `[data-advanced-table-content^="${elem.dataset.advancedTableContent}-"]`
+      );
 
       childRowsAll.forEach((childRow) => {
         const dataContent = childRow.dataset.advancedTableContent;
@@ -382,8 +457,7 @@ export default class PbAdvancedTable extends PbEnhancedElement {
       const currentDepth = parseInt(elem.dataset.rowDepth);
       if (childrenArray.length > currentDepth) {
         // Find the child rows corresponding to this parent row
-        const childRows = this.element
-          .closest("table")
+        const childRows = this.table
           .querySelectorAll(
             `[data-advanced-table-content^="${elem.dataset.advancedTableContent}-"]`
           );
@@ -401,28 +475,39 @@ export default class PbAdvancedTable extends PbEnhancedElement {
 
     const isVisible = elements[0].classList.contains("is-visible");
 
-    isVisible ? this.hideElement(elements) : this.showElement(elements);
-    isVisible ? this.displayDownArrow() : this.displayUpArrow();
+    const isExpanded = toggleVisibility({
+      isVisible,
+      onHide: () => this.hideElement(elements),
+      onShow: () => this.showElement(elements),
+    });
+
+    isExpanded ? this.displayUpArrow() : this.displayDownArrow();
 
     const row = this.element.closest("tr");
     if (row) {
-      row.classList.toggle("bg-silver", !isVisible);
-      row.classList.toggle("pb-bg-row-white", isVisible);
+      row.classList.toggle("bg-silver", isExpanded);
+      row.classList.toggle("pb-bg-row-white", !isExpanded);
     }
 
     this.addBorderRadiusOnLastVisibleRow();
   }
 
   displayDownArrow() {
-    this.element.querySelector(DOWN_ARROW_SELECTOR).style.display =
-      "inline-block";
-    this.element.querySelector(UP_ARROW_SELECTOR).style.display = "none";
+    setArrowVisibility({
+      rootElement: this.element,
+      downSelector: DOWN_ARROW_SELECTOR,
+      upSelector: UP_ARROW_SELECTOR,
+      showDownArrow: true,
+    });
   }
 
   displayUpArrow() {
-    this.element.querySelector(UP_ARROW_SELECTOR).style.display =
-      "inline-block";
-    this.element.querySelector(DOWN_ARROW_SELECTOR).style.display = "none";
+    setArrowVisibility({
+      rootElement: this.element,
+      downSelector: DOWN_ARROW_SELECTOR,
+      upSelector: UP_ARROW_SELECTOR,
+      showDownArrow: false,
+    });
   }
 
   static handleToggleAllHeaders(element) {
@@ -500,3 +585,19 @@ window.expandAllRows = (element) => {
 window.expandAllSubRows = (element, rowDepth) => {
   PbAdvancedTable.handleToggleAllSubRows(element, rowDepth);
 };
+
+// Fix header height and pinned row sticky tops on load (header wrap + collapsed rows)
+function updateAllAdvancedTableStickyHeights() {
+  document.querySelectorAll(".pb_advanced_table").forEach((wrapper) => {
+    PbAdvancedTable.updateStickyHeaderRowHeights(wrapper);
+    PbAdvancedTable.updatePinnedRowsStickyTops(wrapper);
+  });
+}
+
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", updateAllAdvancedTableStickyHeights);
+  } else {
+    updateAllAdvancedTableStickyHeights();
+  }
+}

data/app/pb_kits/playbook/pb_advanced_table/table_body.html.erb

@@ -1,5 +1,22 @@
-<%= pb_content_tag(:tbody) do %>
-        <% object.table_data.each do |row| %>
-          <%= render_row_and_children(row, object.column_definitions, 0, false) %>
-        <% end %>
+<% table_data = object.table_data || [] %>
+<% if object.has_pinned_rows? %>
+  <%= pb_content_tag(:tbody, class: "pinned-rows-tbody") do %>
+    <% next_index = 0 %>
+    <% object.pinned_root_rows.each do |root_info| %>
+      <% row_output, next_index = object.render_row_and_children(root_info[:row], object.column_definitions, root_info[:depth], root_info[:depth] > 0, root_info[:ancestor_ids] || [], root_info[:ancestor_ids]&.first, immediate_parent_row_id: object.row_id_for(root_info[:parent_row]), is_pinned_row: true, pinned_index: next_index, initial_table_data_attributes: root_info[:depth].to_i > 0 ? object.pinned_root_initial_data_attributes(root_info) : nil) %>
+      <%= row_output %>
+    <% end %>
+  <% end %>
+  <%= pb_content_tag(:tbody) do %>
+    <% table_data.each do |row| %>
+      <% result = object.render_row_and_children(row, object.column_definitions, 0, false, skip_pinned_ids: object.pinned_ids_set) %>
+      <%= result.is_a?(Array) ? result[0] : result %>
+    <% end %>
+  <% end %>
+<% else %>
+  <%= pb_content_tag(:tbody) do %>
+    <% table_data.each do |row| %>
+      <%= object.render_row_and_children(row, object.column_definitions, 0, false) %>
+    <% end %>
+  <% end %>
 <% end %>