lightning-base-components 1.26.4-alpha → 1.27.2-alpha

package/src/lightning/toastContainer/toastContainer.lbc.synthetic.css

@@ -1,36 +1,36 @@
 .top,
-:host([data-render-mode="shadow"]) .top {
+:host([data-render-mode='shadow']) .top {
     top: 0;
     bottom: unset;
 }
 
 .bottom,
-:host([data-render-mode="shadow"]) .bottom {
+:host([data-render-mode='shadow']) .bottom {
     bottom: 0;
     top: unset;
 }
 
 .left,
-:host([data-render-mode="shadow"]) .left {
+:host([data-render-mode='shadow']) .left {
     left: 0;
     right: auto;
 }
 
 .right,
-:host([data-render-mode="shadow"]) .right {
+:host([data-render-mode='shadow']) .right {
     left: auto;
     right: 0;
 }
 
 .center,
-:host([data-render-mode="shadow"]) .center {
+:host([data-render-mode='shadow']) .center {
     transform: translate(50%);
     right: 50%;
 }
 
 @media (max-width: 30rem) {
     .center,
-    :host([data-render-mode="shadow"]) .center {
+    :host([data-render-mode='shadow']) .center {
         transform: none;
         right: 0;
         left: 0;

package/src/lightning/tree/tree.slds.css

@@ -4,7 +4,7 @@
  */
 :host([data-render-mode="shadow"]) .slds-tree-container,:host([data-render-mode="shadow"]) 
 .slds-tree_container {
-  min-width: calc(var(--slds-g-sizing-12) + var(--slds-g-sizing-9) + var(--slds-g-sizing-3)) ;
+  min-width: calc(var(--slds-g-sizing-12) + var(--slds-g-sizing-9) + var(--slds-g-sizing-3));
   max-width: var(--slds-c-tree-sizing-max-width, 25rem);
 }
 :host([data-render-mode="shadow"]) .slds-tree-container > .slds-text-heading_label,:host([data-render-mode="shadow"]) 

package/src/lightning/treeGrid/__docs__/treeGrid.md

@@ -26,25 +26,32 @@ the `tel:` URL scheme by specifying the `phone` type. The default type is
 This component implements the
 [tree grid](https://www.lightningdesignsystem.com/components/tree-grid/) blueprint in the Lightning Design System.
 
-Inline editing and sorting of columns are not supported. Supported features
-include:
+These `lightning-datatable` features aren't available on `lightning-tree-grid`:
 
--   Displaying and formatting of columns with appropriate data types
--   Header-level actions
--   Row-level actions
--   Resizing of columns
--   Selecting of rows
--   Sorting of columns by ascending and descending order
--   Text wrapping and clipping
+- Infinite scrolling
+- Inline editing
+- Passing in a fixed width value to a column
+- Specifying the maximum number of rows that can be selected
+- Handling of `resize` event when a column is resized
 
-This component provides styling for up to 20 nested levels. For tree grids that require more than 20 nested levels,
-build your own component.
+Supported features include:
 
-A checkbox is displayed by default in the first column. Set the `hide-checkbox-column` attribute
-to `true` to remove the checkbox.
+- Displaying and formatting of columns with appropriate data types
+- Custom data types
+- Header-level actions
+- Row-level actions
+- Resizing of columns
+- Selecting of rows
+- Sorting of columns by ascending and descending order
+- Text wrapping and clipping
+- Row numbering column
+- Cell content alignment
 
-Initialize your tree grid data using the `data`, `columns`, and `key-field` attributes
-and define their values in JavaScript. Note that `key-field` is required.
+This component provides styling for up to 20 nested levels. For tree grids that require more than 20 nested levels, we recommend that you build your own component.
+
+A checkbox is displayed by default in the first column. Set the `hide-checkbox-column` attribute to `true` to remove the checkbox.
+
+Initialize your tree grid data using the `data`, `columns`, and `key-field` attributes and define their values in JavaScript. Note that `key-field` is required.
 
 This example creates a tree grid with 5 columns, where the
 first column displays a checkbox for row selection. Selecting the checkbox
@@ -53,8 +60,7 @@ event handler. The `expanded-rows` attribute is optional, and expands nested
 items on a row when provided. Selecting a row using the checkbox does not select
 the rows nested below it.
 
-The example includes two buttons whose handlers call `lightning-tree-grid` methods
-to collapse all rows and to show which rows are expanded.
+The example includes two buttons whose handlers call `lightning-tree-grid` methods to collapse all rows and to show which rows are expanded.
 
 ```html
 <template>
@@ -214,18 +220,18 @@ clickToCollapseAll(e) {
 Use the following column properties to customize the behavior and visual
 aspects of your columns.
 
-| Attribute      | Type    | Description                                                                                                                                                                        |
-| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| actions        | object  | Appends a dropdown menu of actions to a column. You must pass in a list of label-name pairs.                                                                                       |
-| cellAttributes | object  | Provides additional customization, such as appending an icon to the output. For more information, see **Appending an Icon to Column Data**                                         |
-| fieldName      | string  | Required. The name that binds the columns attributes to the associated data. Each columns attribute must correspond to an item in the data array.                                  |
-| iconName       | string  | The Lightning Design System name of the icon. Names are written in the format standard:opportunity. The icon is appended to the left of the header label.                          |
-| initialWidth   | integer | The width of the column when it's initialized, which must be within the minColumnWidth and maxColumnWidth values, or within 50px and 1000px if they are not provided.              |
-| label          | string  | Required. The text label displayed in the column header.                                                                                                                           |
-| sortable       | boolean | Specifies whether the column can be sorted. The default is false.                                                                                     |
-| type           | string  | Required. The data type to be used for data formatting. For more information, see **Formatting with Data Types**.                                                                  |
-| typeAttributes | object  | Provides custom formatting with component attributes for the data type. For example, currencyCode for the currency type. For more information, see **Formatting with Data Types**. |
-| wrapText           | boolean | Specifies whether text in a column is wrapped when the table renders. Wrapped text vertically expands a row to reveal its full content. Displaying a number of lines and clipping the rest using `wrap-text-max-lines` isn't supported. For more information, see **Text Wrapping and Clipping**. |
+| Attribute      | Type    | Description                                                                                                                                                                                                                                                                                       |
+| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| fieldName      | string  | Required. The name that binds the columns attributes to the associated data. Each columns attribute must correspond to an item in the data array.                                                                                                                                                 |
+| label          | string  | Required. The text label displayed in the column header.                                                                                                                                                                                                                                          |
+| type           | string  | Required. The data type to be used for data formatting. For more information, see **Formatting with Data Types**.                                                                                                                                                                                 |
+| actions        | object  | Appends a dropdown menu of actions to a column. You must pass in a list of label-name pairs.                                                                                                                                                                                                      |
+| cellAttributes | object  | Provides additional customization using `alignment` and `class` properties, in addition to `icon*` properties, such as for appending an icon to the output. For more information, see **Appending an Icon to Column Data**                                                                        |
+| iconName       | string  | The Lightning Design System name of the icon. Names are written in the format standard:opportunity. The icon is appended to the left of the header label.                                                                                                                                         |
+| initialWidth   | integer | The width of the column when it's initialized, which must be within the `min-column-width` and `max-column-width` values, or within 50px and 1000px if they are not provided.                                                                                                                     |
+| sortable       | boolean | Specifies whether the column can be sorted. The default is false.                                                                                                                                                                                                                                 |
+| typeAttributes | object  | Provides custom formatting with component attributes for the data type. For example, currencyCode for the currency type. For more information, see **Formatting with Data Types**.                                                                                                                |
+| wrapText       | boolean | Specifies whether text in a column is wrapped when the table renders. Wrapped text vertically expands a row to reveal its full content. Displaying a number of lines and clipping the rest using `wrap-text-max-lines` isn't supported. For more information, see **Text Wrapping and Clipping**. |
 
 #### Formatting with Data Types
 
@@ -448,7 +454,7 @@ minimum of 50px and a maximum of 1000px. Users can also resize the column width
 
 ##### Working with Column Widths
 
-You can customize the column widths in many ways. To specify your own width and disable resizing for a specific column, pass in `fixedWidth` to the column property. To specify an initial width and enable resizing for a specific column, pass in `initialWidth` to the column property.
+You can customize the column widths in many ways. To specify an initial width and enable resizing for a specific column, pass in `initialWidth` to the column property.
 
 ```javascript
 const columns = [
@@ -476,32 +482,90 @@ Columns have a default minimum width of 50px and maximum width of 1000px. To cha
 
 To prevent users from resizing columns, specify `resize-column-disabled` in your markup. The table can still adjust its column widths when you resize the browser window or the width of the parent container changes.
 
-`lightning-tree-grid` doesn't support the `resize` event.
+`lightning-tree-grid` doesn't support the `resize` event and the `fixedWidth` column property.
+
+##### Managing the Resizing of Column Widths
+
+The `column-widths-mode` attribute accepts values of `fixed` (default) or `auto`. To provide granular control on your column widths, use this attribute with the `initialWidth` column property.
+
+Widths for the following columns are fixed and cannot be changed.
+
+- Row Number column
+- Selection (checkbox) column
+- Action column
+
+##### Implementing Fixed Width Mode
+
+Render columns with equal widths using `column-widths-mode="fixed"`, which is the default setting. Any content that's too long to be displayed is clipped and appears with a trailing ellipsis. The column width is calculated by taking total available width and dividing equally among the columns.
+
+You can specify your own widths using `initialWidth` only. The widths of the remaining columns without a specified `initialWidth` are equal.
+
+Setting new data on the columns doesn't trigger resizing for columns, unless the new column definition specifies a change in `initialWidth` values. In `fixed` mode, the columns automatically resize and maintain equal widths when:
+
+- The browser window is resized
+- The parent container width for the datatable is changed
+- The `row-number-offset` value is changed
+- More or less data is passed in
+
+When you manually resize a column to a larger width, the other columns maintain their widths, displaying a scrollbar to enable scrolling to the end of the table columns. When you manually resize to a smaller width, the other columns also maintain their widths.
+
+You can resize manually using a mouse or a keyboard. On a keyboard, press enter in the header cell, tab to reach the resizer (column divider), and press the left or right arrow keys. On a touchscreen device, tap on the desired column resizer area, move to the desired width, and then release.
+
+##### Implementing Auto Width Mode
+
+To trigger resizing of columns according to the length or size of data in a column, set `column-widths-mode="auto"`. In `auto` width mode, the columns automatically resize when:
+
+- Data changes in at least one row and the number of rows stays the same
+- The column definition changes, such as a change in a column property or the number of columns
+
+Pass a new reference of columns with changes for resize to take effect. The columns don't resize if there's only a change in the number of records in the data.
+
+Column widths are calculated based on the width of the content displayed in the column and the total width of the table. Specify your own widths for particular columns using the `initialWidth` property. The widths of the columns without the `initialWidth` property are calculated based on the width of the content in the column and the remaining table width. If the columns definition is passed but no data is set yet, the columns are rendered based on the width of the column labels.
+
+A column's width is limited by the `max-column-width` value, or 1000px by default. If a column width is calculated to be wider than the `max-column-width` value, the content is truncated and displayed with an ellipsis. If the column also specifies `wrapText: true`, the column results in a narrower width than if the column has clipped text.
+
+A column's width is also limited by the `min-column-width` value, or 50px by default. If a column width is calculated to be narrower than the `min-column-width` value, the width is set to minimum column width and may have extra white space.
+
+When you manually resize a column, the other columns maintain their widths. This behavior also occurs when a column is manually resized in `fixed` mode.
+
+The columns keep their width ratios while adjusting the column widths when:
+
+- The browser window is resized
+- The parent container width for the datatable is changed
+- The `rowNumberOffset` value is changed
+
+Auto width mode is supported for containers with block display, which corresponds to the `display: block` CSS property.
+`lightning-datatable` doesn't fully support containers with `display:inline-block` or flex properties.
 
 #### Sorting Data By Column
 
 To enable sorting of row data by a column label, set `sortable` to `true` for
-the column on which you want to enable sorting. Set `sortedBy` to match the
-`fieldName` attribute on the column. Clicking a column header sorts rows by
-ascending order unless the `defaultSortDirection` is changed, and clicking it
-subsequently reverses the order. Handle the `onsort` event handler to update
-the table with the new column index and sort direction.
+the column on which you want to enable sorting. Clicking a column header sorts rows by ascending order, and clicking it subsequently reverses the order. Handle the `onsort` event handler to update the table with the new column index and sort direction.
 
-Here's an example of the method that's called by the `onsort`
-event handler.
+Here's an example of an `onsort` event handler.
 
 ```javascript
-        // The method onsort event handler
-        updateColumnSorting(event) {
-            var fieldName = event.detail.fieldName;
-            var sortDirection = event.detail.sortDirection;
-            // assign the latest attribute with the sorted column fieldName and sorted direction
-            this.sortedBy = fieldName;
-            this.sortedDirection = sortDirection;
-            this.data = this.sortData(fieldName, sortDirection);
-       }
+data = data;
+columns = columns;
+sortDirection = 'asc';
+sortedBy;
+// The method onsort event handler
+handleSort(event) {
+    const { fieldName: sortedByField, sortDirection } = event.detail;
+    const cloneData = [...this.data];
+
+    cloneData.sort(this.sortBy(sortedByField, sortDirection === 'asc' ? 1 : -1));
+    this.data = cloneData;
+    this.sortDirection = sortDirection;
+    this.sortedBy = sortedByField;
+}
 ```
 
+The handler assigns `fieldName` to `sortedByField`, which stores the name of the field that is currently being sorted. It also retrieves `sortDirection` from the `sort` event. On first sort, `sortDirection` is `asc`.
+
+`cloneData` creates a shallow copy of the `data` array to avoid mutating the original data. The handler passes in the comparison function `sortBy` and pass it to the [array sort() method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort). It
+updates the `data` property with the sorted data and `sortDirection` with the new sort direction, and `sortedBy` with the column that was sorted.
+
 #### Text Wrapping and Clipping
 
 You can wrap or clip text within columns, which either expands the rows to
@@ -515,15 +579,15 @@ If the number of characters is more than what the column width can display,
 content is clipped by default. Text wrapping is supported only for the
 following data types.
 
--   currency
--   date
--   email
--   location
--   number
--   percent
--   phone
--   text
--   url
+- currency
+- date
+- email
+- location
+- number
+- percent
+- phone
+- text
+- url
 
 For `text` data type, text clipping converts newline characters to spaces and condenses multiple spaces or tabs to one space. Text clipping suppresses line breaks, truncates content to fit a single line in the column, and adds a trailing ellipsis. Text wrapping breaks lines and hyphenates words as needed to fit the column.
 
@@ -568,7 +632,6 @@ You can add a `displayValue` on the dropdown arrow for a row. This `displayValue
     }
 ```
 
-
 ##### Provide an Accessible Label for the Table
 
 Use the `aria-label` attribute to provide a more descriptive label for the table for assistive technology. The `aria-label` attribute and its value are passed down to the rendered `table` element.
@@ -622,9 +685,9 @@ When using custom types, add additional attributes to make all elements of the c
 
 Columns can be resized in action mode. First, navigate to the header using the arrow keys. Then, press the Tab key to activate the column divider to resize a column. You can resize a column by increasing or decreasing its width using one of the following key combinations.
 
--   Right and Left Arrow keys
--   Up and Down Arrow keys
--   Page Up and Page Down keys
+- Right and Left Arrow keys
+- Up and Down Arrow keys
+- Page Up and Page Down keys
 
 When you resize a column, the new column width is announced by assistive technology. To finish resizing the column and return to navigation mode, press the Esc key.
 
@@ -653,10 +716,11 @@ The event fired when a column is sorted.
 
 The `sort` event returns the following parameters.
 
-| Parameter     | Type   | Description                                                    |
-| ------------- | ------ | -------------------------------------------------------------- |
-| fieldName     | string | The fieldName that controls the sorting.                       |
-| sortDirection | string | The sorting direction. Valid options include 'asc' and 'desc'. |
+| Parameter         | Type    | Description                                                    |
+| ----------------- | ------- | -------------------------------------------------------------- |
+| fieldName         | string  | The fieldName that controls the sorting.                       |
+| isMultiColumnSort | boolean | Reserved for internal use. Defaults to false.                  |
+| sortDirection     | string  | The sorting direction. Valid options include 'asc' and 'desc'. |
 
 The event properties are as follows.
 

package/src/lightning/treeGrid/treeGrid.js

@@ -34,8 +34,10 @@ export default class LightningTreeGrid extends LightningShadowBaseClass {
     _ogDatatableCustomTypes;
 
     /**
-     * Pass through for column-widths-mode on lightning-datatable
+     * Specifies how column widths are calculated. Set to 'fixed' for columns with equal widths.
+     * Set to 'auto' for column widths that are based on the width of the column content and the table width. The default is 'fixed'.
      * @type {string}
+     * @default fixed
      */
     @api columnWidthsMode;