playbook_ui_docs 16.7.0 → 16.8.0.pre.alpha.PLAY2935formbuilderrequiredindicatorbug16780

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0fc6745132e00861350832917eae46af8cb87d4241c65d77b654768cae6a5e3
-  data.tar.gz: '08e12f515845e5bfd957ef67a253280c2cafd28274d6cc8bfd58831eeebfc408'
+  metadata.gz: 3199fb4e6cb177716055d8b460d66e879626f02e4f3bb6ad12edb9b22725c2dc
+  data.tar.gz: 38ca89a03adf56cb1ee16334899f8e8f4e0315a036ed54a3746a0c1c3b7ef920
 SHA512:
-  metadata.gz: 7c694113752216ac6e5a606edc4b7c85ed5ee3487f4cc9603e81fedcb353664cd9595eedf94bc77a5040cf5215d63535c6f0e4a942db3bffabaabc1d3f318503
-  data.tar.gz: bfc611733a3ddc0c39235cb430534d5bf1905037766a05b18eb3353ee331661a4168899fc8c8d1e5ae48826bc24d5e7c785beec6572e1340e75018ed8bd97e09
+  metadata.gz: 49304bcd06237aee0a231c817c6cbcd10f4942cc54754457c5372d555e2e2e85819747d287871ad519e083e81828eccd634a432e8b26541d5da5c9537e579555
+  data.tar.gz: 45b87cdd2c9a8a291ed39c03a509d225425db6c337a19239bbbab2d0d6eb3468662cb01a9819683af505323c19f234063b4d60e31a050569c65a6f02b4fdf30e

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

@@ -10,6 +10,7 @@ const AdvancedTableColumnStyling = (props) => {
       accessor: "year",
       label: "Year",
       cellAccessors: ["quarter", "month", "day"],
+      columnStyling: { width: 124 },
     },
     {
       accessor: "newEnrollments",

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

@@ -6,4 +6,10 @@ The `columnStyling` prop is an optional item that can be used within `columnDefi
 
 3) `fontColor`: This will allow you to control the font color for a given column.
 
+4) Column width: optional keys on `columnStyling` are `minWidth`, `width`, and `maxWidth` (numbers = pixels; CSS strings allowed). This example sets `width` on Year for a fixed hierarchy column (see the width doc for `minWidth` and bands).
+
+Fixed width: pass `width` only (or TanStack `size` only) and Playbook sets min and max to the same value automatically — you do not need all three for an exact width.
+
+See [Column Styling: Width](https://playbook.powerapp.cloud/kits/advanced_table/react#column-styling-width) for the full guide (Playbook ↔ TanStack mapping, floor-only vs bands, and when to use one vs three values).
+
 `columnStyling` can be used within the columnDefinition of all the columns or some of them, as shown. Each column has its own individual control in this way. 

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

@@ -0,0 +1,57 @@
+import React from "react"
+import AdvancedTable from "../_advanced_table"
+import MOCK_DATA from "./advanced_table_mock_data.json"
+
+/**
+ * Kit doc: compares fixed width, floor-only, TanStack band, and min/preferred/max band.
+ */
+const AdvancedTableColumnStylingWidth = (props) => {
+  const columnDefinitions = [
+    {
+      accessor: "year",
+      label: "Year (fixed)",
+      cellAccessors: ["quarter", "month", "day"],
+      // width alone locks min + max to the same value (128px).
+      columnStyling: { width: 128 },
+    },
+    {
+      accessor: "newEnrollments",
+      label: "Enrollments (floor)",
+      columnStyling: { minWidth: 160 },
+    },
+    {
+      accessor: "scheduledMeetings",
+      label: "Meetings (TanStack band)",
+      size: 200,
+      minSize: 160,
+      maxSize: 240,
+    },
+    {
+      accessor: "attendanceRate",
+      label: "Attendance (min / pref / max)",
+      columnStyling: { minWidth: 108, width: 124, maxWidth: 168 },
+    },
+    {
+      accessor: "completedClasses",
+      label: "Completed",
+    },
+    {
+      accessor: "classCompletionRate",
+      label: "Completion %",
+    },
+    {
+      accessor: "graduatedStudents",
+      label: "Graduated",
+    },
+  ]
+
+  return (
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        tableData={MOCK_DATA}
+        {...props}
+    />
+  )
+}
+
+export default AdvancedTableColumnStylingWidth

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

@@ -0,0 +1,66 @@
+AdvancedTable column width is controlled in two equivalent places on each leaf `columnDefinitions` entry. Playbook maps them to inline styles on header and body cells (and forwards numeric values into TanStack Table’s column model).
+
+1) Playbook `columnStyling` and TanStack `ColumnDef` use the same three ideas:
+
+- Preferred / target width: `columnStyling` `width` maps to TanStack `size` on the same column object.
+- Minimum width (floor): `columnStyling` `minWidth` maps to TanStack `minSize`.
+- Maximum width (ceiling): `columnStyling` `maxWidth` maps to TanStack `maxSize`.
+
+Numbers are pixels. You can also pass CSS length strings on `columnStyling` (e.g. `"12rem"`, `"200px"`). TanStack fields accept numbers only.
+
+If both APIs set the same axis, `columnStyling` wins for that axis when Playbook builds cell styles.
+
+2) Fixed width: set `width` only
+
+If you pass only `width` (or only `size`) and do not set `minWidth` / `maxWidth` (or `minSize` / `maxSize`), Playbook treats that as a fixed column: it sets all three to the same value under the hood so you do not have to repeat yourself.
+
+```jsx
+columnStyling: { width: 128 }
+// Applied as width, minWidth, and maxWidth: 128px
+```
+
+```jsx
+size: 200
+// Forwarded as size, minSize, and maxSize: 200
+```
+
+Use this when the column should stay one width (e.g. a hierarchy column with expand controls).
+
+3) Floor only: `minWidth` / `minSize`
+
+Set only a minimum when the column may grow with the table or content but must not shrink below a baseline (common fix for horizontal “jump” when rows expand):
+
+```jsx
+columnStyling: { minWidth: 160 }
+```
+
+4) Flexible band: min + preferred + max
+
+Set two or three values when you want a range. CSS uses preferred `width` clamped between `minWidth` and `maxWidth`:
+
+- `minWidth`: won’t shrink below this.
+- `width`: preferred size when space allows.
+- `maxWidth`: won’t grow above this.
+
+Example from the table below (Attendance): `minWidth: 108`, `width: 124`, `maxWidth: 168` → preferred 124px, allowed between 108 and 168.
+
+You only need all three when you want that band. If min and max are omitted, `width` alone is enough for a fixed column.
+
+5) TanStack band without `columnStyling`
+
+The Meetings column uses only TanStack fields:
+
+```jsx
+{ accessor: "scheduledMeetings", size: 200, minSize: 160, maxSize: 240 }
+```
+
+Playbook applies the same min / preferred / max idea to cell styles. Setting only `size: 200` would lock all three to 200, same as `width: 200` in `columnStyling`.
+
+6) What the example table shows
+
+- Year (fixed): `columnStyling: { width: 128 }` — locked to 128px.
+- Enrollments (floor): `columnStyling: { minWidth: 160 }` — at least 160px; can grow.
+- Meetings (TanStack band): `size` / `minSize` / `maxSize` — preferred 200px, between 160–240.
+- Attendance (min / pref / max): all three in `columnStyling` — preferred 124px, between 108–168.
+
+Grouped columns: put width options on leaf definitions (columns with an `accessor`), not on parent group headers.

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_enable_toggle_expansion_rails.html.erb

@@ -0,0 +1,62 @@
+<%
+  column_definitions = [
+    {
+      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",
+    }
+  ]
+
+  subrow_headers = ["Quarter", "Month", "Day"]
+%>
+
+<%= pb_rails("title", props: { size: 4, text: "Normal Structure", margin_bottom: "sm" }) %>
+
+<%= pb_rails("advanced_table", props: {
+  id: "enable-toggle-expansion-normal",
+  table_data: @table_data,
+  column_definitions: column_definitions,
+  enable_toggle_expansion: "all"
+}) %>
+
+<%= pb_rails("title", props: { size: 4, text: "Subcomponent Structure", margin_top: "lg", margin_bottom: "sm" }) %>
+
+<%= pb_rails("advanced_table", props: { id: "enable-toggle-expansion-subcomponents" }) do %>
+  <%= pb_rails("advanced_table/table_header", props: {
+    table_id: "enable-toggle-expansion-subcomponents",
+    table_data: @table_data,
+    column_definitions: column_definitions,
+    enable_toggle_expansion: "all"
+  }) %>
+  <%= pb_rails("advanced_table/table_body", props: {
+    table_id: "enable-toggle-expansion-subcomponents",
+    table_data: @table_data,
+    column_definitions: column_definitions,
+    subrow_headers: subrow_headers,
+    enable_toggle_expansion: "all"
+  }) %>
+<% end %>

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

@@ -0,0 +1,7 @@
+`enable_toggle_expansion` controls where AdvancedTable renders toggle-all expansion controls. It accepts `"header"`, `"all"`, or `"none"` and defaults to `"header"`.
+
+When using the normal Rails structure, pass `enable_toggle_expansion` to `advanced_table`. The parent kit renders its own `table_header` and `table_body`, so the prop is passed down automatically.
+
+When using the Rails subcomponent structure, pass `enable_toggle_expansion` directly to the subcomponents that need it. `advanced_table/table_header` uses it for the table header toggle-all button. **NOTE**: you must pass `table_data` to `advanced_table/table_header` as well so it can detect whether expandable rows exist. `advanced_table/table_body` uses it for nested subrow header toggle controls, such as when `subrow_headers` is present.
+
+Use `"all"` when you want toggle-all controls in both the table header and subrow headers. Use `"header"` when you only want the table header toggle-all control. Use `"none"` to suppress the header toggle-all control.

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

@@ -1,13 +1,21 @@
 import React from "react"
 import AdvancedTable from '../../pb_advanced_table/_advanced_table'
-import MOCK_DATA from "./advanced_table_mock_data.json"
+
+const tableData = Array.from({ length: 15 }, (_, index) => ({
+  year: String(2020 + index),
+  newEnrollments: String(20 + index),
+  scheduledMeetings: String(10 + index),
+  attendanceRate: `${50 + index}%`,
+  completedClasses: String(3 + index),
+  classCompletionRate: `${30 + index}%`,
+  graduatedStudents: String(19 + index),
+}))
 
 const AdvancedTableStickyHeader = (props) => {
   const columnDefinitions = [
     {
       accessor: "year",
       label: "Year",
-      cellAccessors: ["quarter", "month", "day"],
     },
     {
       accessor: "newEnrollments",
@@ -40,11 +48,11 @@ const AdvancedTableStickyHeader = (props) => {
   }
 
   return (
-    <div>
+    <div style={{ maxHeight: "320px", overflowY: "auto" }}>
       <AdvancedTable
           columnDefinitions={columnDefinitions}
           responsive="none"
-          tableData={MOCK_DATA}
+          tableData={tableData}
           tableProps={tableProps}
           {...props}
       />

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

@@ -1,3 +1,7 @@
 The `TableProps` prop can also be used to render a sticky header for the Advanced Table.
 
+This doc example uses a scroll container with flat rows so sticky behavior is visible in the docs without expanding subrows. Scroll inside the preview to see the header stick.
+
+This example builds flat table data inline for the docs preview. For typical `tableData` setup, see [Default (Required Props)](/kits/advanced_table/default/react#advanced_table_default).
+
 This doc example showcases how to set a sticky header for a nonresponsive table (see the `responsive` prop set to "none"). To achieve sticky header AND responsive functionality, see the "Sticky Header for Responsive Table" doc example below.

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_sticky_header_rails.html.erb

@@ -2,7 +2,6 @@
     {
       accessor: "year",
       label: "Year",
-      cellAccessors: ["quarter", "month", "day"],
     },
     {
       accessor: "newEnrollments",
@@ -30,4 +29,19 @@
     }
 ] %>
 
-<%= pb_rails("advanced_table", props: { id: "sticky_header_table", table_data: @table_data, column_definitions: column_definitions, responsive: "none", table_props: { sticky: true }}) %>
+<% table_data = 15.times.map do |index|
+  {
+    year: (2020 + index).to_s,
+    id: (2020 + index).to_s,
+    newEnrollments: (20 + index).to_s,
+    scheduledMeetings: (10 + index).to_s,
+    attendanceRate: "#{50 + index}%",
+    completedClasses: (3 + index).to_s,
+    classCompletionRate: "#{30 + index}%",
+    graduatedStudents: (19 + index).to_s,
+  }
+end %>
+
+<div style="max-height: 320px; overflow-y: auto;">
+  <%= pb_rails("advanced_table", props: { id: "sticky_header_table", table_data: table_data, column_definitions: column_definitions, responsive: "none", table_props: { sticky: true }}) %>
+</div>

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

@@ -1,3 +1,7 @@
 The `table_props` prop can also be used to render a sticky header for the Advanced Table.
 
+This doc example uses a scroll container with flat rows so sticky behavior is visible in the docs without expanding subrows. Scroll inside the preview to see the header stick.
+
+This example builds flat table data inline for the docs preview. For typical `table_data` setup, see [Default (Required Props)](/kits/advanced_table/default/rails#advanced_table_beta).
+
 This doc example showcases how to set a sticky header for a nonresponsive table (see the `responsive` prop set to "none"). To achieve sticky header AND responsive functionality, see the "[Sticky Header for Responsive Table](https://playbook.powerapp.cloud/kits/advanced_table/react#sticky-header-for-responsive-table)" doc example below.

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

@@ -0,0 +1,68 @@
+import React from "react"
+import AdvancedTable from "../../pb_advanced_table/_advanced_table"
+import Title from "../../pb_title/_title"
+
+const COLUMN_COUNT = 10
+const ROW_COUNT = 40
+
+const columnDefinitions = [
+  {
+    accessor: "region",
+    label: "Region",
+    id: "region",
+    columnStyling: { minWidth: 160 },
+  },
+  ...Array.from({ length: COLUMN_COUNT }, (_, index) => ({
+    accessor: `metric${index + 1}`,
+    label: `Metric ${index + 1}`,
+    id: `metric${index + 1}`,
+    columnStyling: { minWidth: 180 },
+  })),
+]
+
+const tableData = Array.from({ length: ROW_COUNT }, (_, row) => ({
+  region: `Region ${row + 1}`,
+  ...Object.fromEntries(
+    Array.from({ length: COLUMN_COUNT }, (_, col) => [
+      `metric${col + 1}`,
+      String((row + 1) * (col + 1)),
+    ])
+  ),
+}))
+
+const tableProps = { sticky: true }
+
+const AdvancedTableStickyScrollLimitation = (props) => (
+  <div>
+    <Title
+        size={4}
+        text="Without maxHeight"
+        {...props}
+    />
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        responsive="none"
+        stickyLeftColumn={["region"]}
+        tableData={tableData}
+        tableProps={tableProps}
+        {...props}
+    />
+    <Title
+        paddingTop="sm"
+        size={4}
+        text="With maxHeight"
+        {...props}
+    />
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        maxHeight="sm"
+        responsive="none"
+        stickyLeftColumn={["region"]}
+        tableData={tableData}
+        tableProps={tableProps}
+        {...props}
+    />
+  </div>
+)
+
+export default AdvancedTableStickyScrollLimitation

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

@@ -0,0 +1,7 @@
+`stickyLeftColumn` adds horizontal overflow to the table wrapper. Without `maxHeight`, the page scrolls vertically while the table scrolls horizontally — two scroll containers.
+
+Sticky columns work in that setup, but the sticky header cannot stick to the page. Scroll down on the page, then scroll the first table horizontally to see the conflict.
+
+The second table uses `maxHeight` so both axes share one scroll container. The header sticks to the top of the table box instead of the page.
+
+For a typical implementation with subrows, see [Sticky Columns with Sticky Header](#sticky-columns-with-sticky-header).

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_table_props_sticky_header.html.erb

@@ -2,7 +2,6 @@
     {
       accessor: "year",
       label: "Year",
-      cellAccessors: ["quarter", "month", "day"],
     },
     {
       accessor: "newEnrollments",
@@ -30,4 +29,19 @@
     }
 ] %>
 
-<%= pb_rails("advanced_table", props: { id: "table_props_sticky_table", table_data: @table_data, column_definitions: column_definitions, max_height: "xs", table_props: { sticky: true }}) %>
+<% table_data = 15.times.map do |index|
+  {
+    year: (2020 + index).to_s,
+    id: (2020 + index).to_s,
+    newEnrollments: (20 + index).to_s,
+    scheduledMeetings: (10 + index).to_s,
+    attendanceRate: "#{50 + index}%",
+    completedClasses: (3 + index).to_s,
+    classCompletionRate: "#{30 + index}%",
+    graduatedStudents: (19 + index).to_s,
+  }
+end %>
+
+<div style="max-height: 320px; overflow-y: auto;">
+  <%= pb_rails("advanced_table", props: { id: "table_props_sticky_table", table_data: table_data, column_definitions: column_definitions, table_props: { sticky: true }}) %>
+</div>

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

@@ -1,13 +1,21 @@
 import React from "react"
 import AdvancedTable from '../../pb_advanced_table/_advanced_table'
-import MOCK_DATA from "./advanced_table_mock_data.json"
+
+const tableData = Array.from({ length: 15 }, (_, index) => ({
+  year: String(2020 + index),
+  newEnrollments: String(20 + index),
+  scheduledMeetings: String(10 + index),
+  attendanceRate: `${50 + index}%`,
+  completedClasses: String(3 + index),
+  classCompletionRate: `${30 + index}%`,
+  graduatedStudents: String(19 + index),
+}))
 
 const AdvancedTableTablePropsStickyHeader = (props) => {
   const columnDefinitions = [
     {
       accessor: "year",
       label: "Year",
-      cellAccessors: ["quarter", "month", "day"],
     },
     {
       accessor: "newEnrollments",
@@ -40,11 +48,10 @@ const AdvancedTableTablePropsStickyHeader = (props) => {
   }
 
   return (
-    <div>
+    <div style={{ maxHeight: "320px", overflowY: "auto" }}>
       <AdvancedTable
           columnDefinitions={columnDefinitions}
-          maxHeight="xs"
-          tableData={MOCK_DATA}
+          tableData={tableData}
           tableProps={tableProps}
           {...props}
       />

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

@@ -2,6 +2,10 @@ Create a sticky header that works for responsive Advanced Tables by setting `sti
 
 **NOTE**: This behavior requires a `max_height` to work. The header is sticky within the table container, allowing for it to work along with the first column stickiness of a responsive table on smaller screen sizes.
 
+Scroll inside the table preview to see the header stick.
+
+This example builds flat table data inline for the docs preview. For typical `table_data` setup, see [Default (Required Props)](/kits/advanced_table/default/rails#advanced_table_beta).
+
 Expand the table above to see this in action.
 
 A sticky header on a nonresponsive table is demonstrated in the ["Sticky Header"](https://playbook.powerapp.cloud/kits/advanced_table#sticky-header) doc example above.

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

@@ -1,7 +1,9 @@
-Create a sticky header that works for responsive Advanced Tables by setting `sticky: true` via `tableProps` and giving the AdvancedTable a `maxHeight` using our [Max Height](https://playbook.powerapp.cloud/global_props/max_height) global prop. 
+Create a sticky header that works for responsive Advanced Tables by setting `sticky: true` via `tableProps` and wrapping the table in a scroll container (or using `maxHeight`).
 
-**NOTE**: This behavior requires a `maxHeight` to work. The header is sticky within the table container, allowing for it to work along with the first column stickiness of a responsive table on smaller screen sizes.
+**NOTE**: The header is sticky within the table scroll area. The live example uses flat rows so you can scroll inside the preview without expanding subrows.
 
-Expand the table above to see this in action.
+This example builds flat table data inline for the docs preview. For typical `tableData` setup, see [Default (Required Props)](/kits/advanced_table/default/react#advanced_table_default).
+
+Expand the table above to see responsive behavior in action.
 
 A sticky header on a nonresponsive table is demonstrated in the ["Sticky Header"](https://playbook.powerapp.cloud/kits/advanced_table/react#sticky-header) doc example above.