@brightspace-ui/core 2.175.0 → 2.176.0

package/components/button/README.md

@@ -175,6 +175,27 @@ To make your `d2l-button-icon` accessible, use the following properties when app
 </d2l-button-icon>
 ```
 
+## Add Button [d2l-button-add]
+
+The `d2l-button-add` element is for quickly adding new items inline (for example in a list).
+
+<!-- docs: demo code properties name:d2l-button-add display:block autoSize:false size:xsmall -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/button/button-add.js';
+</script>
+<d2l-button-add text="Add New Item"></d2l-button-add>
+```
+
+<!-- docs: start hidden content -->
+### Properties
+
+| Property | Type | Description |
+|--|--|--|
+| `text` | String, required | The text associated with the button. When mode is "icon-and-text", this text is displayed next to the icon. Otherwise this text is in a tooltip. |
+| `mode` | String | Display mode of the component. Defaults to "icon" (plus icon is always visible). Other options are "icon-and-text" (plus icon and text are always visible), and "icon-when-interacted" (plus icon is only visible when hover or focus). |
+<!-- docs: end hidden content -->
+
 ## Floating Buttons [d2l-floating-buttons]
 
 See [floating buttons](https://github.com/BrightspaceUI/core/tree/main/components/button/floating-buttons.md).

package/components/button/button-add.js

@@ -11,9 +11,9 @@ import { PropertyRequiredMixin } from '../../mixins/property-required/property-r
 import { RtlMixin } from '../../mixins/rtl/rtl-mixin.js';
 
 const MODE = {
-	ICON: 'icon',
-	ICON_AND_TEXT: 'icon-and-text',
-	ICON_WHEN_INTERACTED: 'icon-when-interacted'
+	icon: 'icon',
+	icon_and_text: 'icon-and-text',
+	icon_when_interacted: 'icon-when-interacted'
 };
 
 /**
@@ -23,12 +23,12 @@ class ButtonAdd extends RtlMixin(PropertyRequiredMixin(FocusMixin(LocalizeCoreEl
 	static get properties() {
 		return {
 			/**
-			 * Display mode of the component. Defaults to "icon" (plus icon is always visible). Other options are "icon-and-text" (plus icon and text are always visible), and "icon-when-interacted" (plus icon is only visible when hover or focus).
+			 * Display mode of the component. Defaults to `icon` (plus icon is always visible). Other options are `icon-and-text` (plus icon and text are always visible), and `icon-when-interacted` (plus icon is only visible when hover or focus).
 			 * @type {'icon'|'icon-and-text'|'icon-when-interacted'}
 			 */
 			mode: { type: String, reflect: true },
 			/**
-			 * When text-visible is true, the text to show in the button. When text-visible is false, the text to show in the tooltip.
+			 * The text associated with the button. When mode is `icon-and-text` this text is displayed next to the icon, otherwise this text is in a tooltip.
 			 * @type {string}
 			 */
 			text: { type: String, required: true }
@@ -155,7 +155,7 @@ class ButtonAdd extends RtlMixin(PropertyRequiredMixin(FocusMixin(LocalizeCoreEl
 	constructor() {
 		super();
 
-		this.mode = MODE.ICON;
+		this.mode = MODE.icon;
 
 		this._buttonId = getUniqueId();
 	}
@@ -166,13 +166,13 @@ class ButtonAdd extends RtlMixin(PropertyRequiredMixin(FocusMixin(LocalizeCoreEl
 
 	render() {
 		const text = this.text || this.localize('components.button-add.addItem');
-		const id = !this.mode !== MODE.ICON_AND_TEXT ? this._buttonId : undefined;
-		const offset = this.mode === MODE.ICON_WHEN_INTERACTED ? 23 : 18;
+		const id = !this.mode !== MODE.icon_and_text ? this._buttonId : undefined;
+		const offset = this.mode === MODE.icon_when_interacted ? 23 : 18;
 
-		const content = this.mode !== MODE.ICON_AND_TEXT
-			? html`<d2l-button-add-icon-text ?visible-on-ancestor="${this.mode === MODE.ICON_WHEN_INTERACTED}" animation-type="opacity"></d2l-button-add-icon-text>`
+		const content = this.mode !== MODE.icon_and_text
+			? html`<d2l-button-add-icon-text ?visible-on-ancestor="${this.mode === MODE.icon_when_interacted}" animation-type="opacity"></d2l-button-add-icon-text>`
 			: html`<d2l-button-add-icon-text text="${text}"></d2l-button-add-icon-text>`;
-		const tooltip = this.mode !== MODE.ICON_AND_TEXT
+		const tooltip = this.mode !== MODE.icon_and_text
 			? html`<d2l-tooltip class="vdiff-target" delay="100" offset="${offset}" for="${this._buttonId}" for-type="label">${text}</d2l-tooltip>`
 			: nothing;
 

package/components/list/list-item-generic-layout.js

@@ -69,7 +69,12 @@ class ListItemGenericLayout extends RtlMixin(LitElement) {
 					[control-end content-start] minmax(0, auto)
 					[content-end actions-start] minmax(0, min-content)
 					[end actions-end];
-				grid-template-rows: [main-start] [main-end add-start] [add-end nested-start] [nested-end];
+				grid-template-rows:
+					[start add-top-start] minmax(0, min-content)
+					[add-top-end main-start] minmax(0, min-content)
+					[main-end add-start] minmax(0, min-content)
+					[add-end nested-start] minmax(0, min-content)
+					[nested-end end];
 			}
 
 			:host([align-nested="control"]) ::slotted([slot="nested"]) {
@@ -92,7 +97,7 @@ class ListItemGenericLayout extends RtlMixin(LitElement) {
 			::slotted([slot="outside-control-container"]),
 			::slotted([slot="control-container"]),
 			::slotted([slot="drop-target"]) {
-				grid-row: 1 / 2;
+				grid-row: 2 / 3;
 			}
 
 			::slotted([slot="outside-control"]) {
@@ -169,12 +174,19 @@ class ListItemGenericLayout extends RtlMixin(LitElement) {
 
 			::slotted([slot="nested"]) {
 				grid-column: content-start / end;
-				grid-row: nested-start / nested-end;
+				grid-row: nested;
 			}
+
 			::slotted([slot="add"]) {
-				grid-column: color-start / end;
 				grid-row: add;
 			}
+			::slotted([slot="add-top"]) {
+				grid-row: add-top;
+			}
+			::slotted([slot="add-top"]),
+			::slotted([slot="add"]) {
+				grid-column: color-start / end;
+			}
 		`;
 	}
 
@@ -208,6 +220,8 @@ class ListItemGenericLayout extends RtlMixin(LitElement) {
 
 	render() {
 		return html`
+			<slot name="add-top" class="d2l-cell" data-cell-num="10"></slot>
+
 			<slot name="control-container"></slot>
 			<slot name="outside-control-container"></slot>
 

package/components/list/list-item-mixin.js

@@ -60,6 +60,10 @@ export const ListItemMixin = superclass => class extends composeMixins(
 			 * @type {string}
 			 */
 			color: { type: String },
+			/**
+			 * @ignore
+			 */
+			first: { type: Boolean, reflect: true },
 			/**
 			 * Whether to allow the drag target to be the handle only rather than the entire cell
 			 * @type {boolean}
@@ -143,6 +147,7 @@ export const ListItemMixin = superclass => class extends composeMixins(
 			:host([selected]:not([selection-disabled]):not([skeleton])) [slot="control-container"]::before,
 			:host([selected]:not([selection-disabled]):not([skeleton])) [slot="control-container"]::after,
 			:host([_show-add-button]) [slot="control-container"]::after,
+			:host([_show-add-button]) [slot="control-container"]::before,
 			:host(:first-of-type[_nested]) [slot="control-container"]::before {
 				border-top-color: transparent;
 			}
@@ -380,7 +385,8 @@ export const ListItemMixin = superclass => class extends composeMixins(
 				margin-right: -6px;
 			}
 
-			[slot="add"] {
+			[slot="add"],
+			[slot="add-top"] {
 				margin-bottom: -4px;
 				margin-top: -3px;
 			}
@@ -399,6 +405,7 @@ export const ListItemMixin = superclass => class extends composeMixins(
 
 	constructor() {
 		super();
+		this.first = false;
 		this.noPrimaryAction = false;
 		this.paddingType = 'normal';
 		this._contentId = getUniqueId();
@@ -553,9 +560,10 @@ export const ListItemMixin = superclass => class extends composeMixins(
 		}
 	}
 
-	_handleButtonAddClick() {
+	_handleButtonAddClick(e) {
+		const position = e.target.hasAttribute('data-is-first') ? 'before' : 'after';
 		/** @ignore */
-		this.dispatchEvent(new CustomEvent('d2l-list-item-add-button-click', { bubbles: true }));
+		this.dispatchEvent(new CustomEvent('d2l-list-item-add-button-click', { bubbles: true, detail: { position } }));
 	}
 
 	_isListItem(node) {
@@ -608,6 +616,7 @@ export const ListItemMixin = superclass => class extends composeMixins(
 		const nestedList = this._getNestedList();
 		if (this._hasNestedList !== !!nestedList) {
 			this._hasNestedList = !!nestedList;
+			this._hasNestedListAddButton = nestedList.hasAttribute('add-button');
 			/** @ignore */
 			this.dispatchEvent(new CustomEvent('d2l-list-item-nested-change', { bubbles: true, composed: true }));
 		}
@@ -640,6 +649,11 @@ export const ListItemMixin = superclass => class extends composeMixins(
 				data-separators="${ifDefined(this._separators)}"
 				?grid-active="${this.role === 'rowgroup'}"
 				?no-primary-action="${this.noPrimaryAction}">
+				${this._showAddButton && this.first ? html`
+				<div slot="add-top">
+					<d2l-button-add text="${addButtonText}" mode="icon-when-interacted" @click="${this._handleButtonAddClick}" data-is-first></d2l-button-add>
+				</div>
+				` : nothing}
 				<div slot="outside-control-container"></div>
 				${this._renderDropTarget()}
 				${this._renderDragHandle(this._renderOutsideControl)}
@@ -682,7 +696,7 @@ export const ListItemMixin = superclass => class extends composeMixins(
 					class="d2l-list-item-actions-container">
 					<slot name="actions" class="d2l-list-item-actions">${actions}</slot>
 				</div>
-				${this._showAddButton ? html`
+				${this._showAddButton && !this._hasNestedListAddButton ? html`
 				<div slot="add">
 					<d2l-button-add text="${addButtonText}" mode="icon-when-interacted" @click="${this._handleButtonAddClick}"></d2l-button-add>
 				</div>

package/components/list/list.js

@@ -120,6 +120,9 @@ class List extends PageableMixin(SelectionMixin(LitElement)) {
 				--d2l-list-item-color-border-radius: 3px;
 				--d2l-list-item-color-width: 3px;
 			}
+			:host([add-button]) ::slotted([slot="controls"]) {
+				margin-bottom: calc(6px + 0.4rem); /* controls section margin-bottom + spacing for add-button */
+			}
 		`;
 	}
 
@@ -319,8 +322,12 @@ class List extends PageableMixin(SelectionMixin(LitElement)) {
 
 	_handleListItemAddButtonClick(e) {
 		e.stopPropagation();
-		/** Dispatched when the add button directly after the item is clicked. Event detail includes the key of the item directly above where the add button was clicked. */
-		this.dispatchEvent(new CustomEvent('d2l-list-add-button-click', { detail: { key: e.target.key } }));
+		/**
+		 * Dispatched when the add button directly after the item is clicked. Event detail includes position ('before' or 'after') and key.
+		 * The key belongs to the list item adjacent to where the new item should be positioned.
+		 * The position represents where the new item should be positioned relative to the item with that key.
+		 * */
+		this.dispatchEvent(new CustomEvent('d2l-list-add-button-click', { detail: { key: e.target.key, position: e.detail.position } }));
 	}
 
 	_handleListItemNestedChange(e) {
@@ -368,6 +375,10 @@ class List extends PageableMixin(SelectionMixin(LitElement)) {
 
 	_handleSlotChange() {
 		this._updateItemShowingCount();
+		this.getItems().forEach((item, i) => {
+			if (i === 0) item.first = true;
+			else item.first = false;
+		});
 
 		/** @ignore */
 		this.dispatchEvent(new CustomEvent('d2l-list-item-showing-count-change', {

package/custom-elements.json

@@ -350,29 +350,29 @@
       "attributes": [
         {
           "name": "text",
-          "description": "When text-visible is true, the text to show in the button. When text-visible is false, the text to show in the tooltip.",
+          "description": "The text associated with the button. When mode is `icon-and-text` this text is displayed next to the icon, otherwise this text is in a tooltip.",
           "type": "string"
         },
         {
           "name": "mode",
-          "description": "Display mode of the component. Defaults to \"icon\" (plus icon is always visible). Other options are \"icon-and-text\" (plus icon and text are always visible), and \"icon-when-interacted\" (plus icon is only visible when hover or focus).",
+          "description": "Display mode of the component. Defaults to `icon` (plus icon is always visible). Other options are `icon-and-text` (plus icon and text are always visible), and `icon-when-interacted` (plus icon is only visible when hover or focus).",
           "type": "'icon'|'icon-and-text'|'icon-when-interacted'",
-          "default": "\"ICON\""
+          "default": "\"icon\""
         }
       ],
       "properties": [
         {
           "name": "text",
           "attribute": "text",
-          "description": "When text-visible is true, the text to show in the button. When text-visible is false, the text to show in the tooltip.",
+          "description": "The text associated with the button. When mode is `icon-and-text` this text is displayed next to the icon, otherwise this text is in a tooltip.",
           "type": "string"
         },
         {
           "name": "mode",
           "attribute": "mode",
-          "description": "Display mode of the component. Defaults to \"icon\" (plus icon is always visible). Other options are \"icon-and-text\" (plus icon and text are always visible), and \"icon-when-interacted\" (plus icon is only visible when hover or focus).",
+          "description": "Display mode of the component. Defaults to `icon` (plus icon is always visible). Other options are `icon-and-text` (plus icon and text are always visible), and `icon-when-interacted` (plus icon is only visible when hover or focus).",
           "type": "'icon'|'icon-and-text'|'icon-when-interacted'",
-          "default": "\"ICON\""
+          "default": "\"icon\""
         },
         {
           "name": "documentLocaleSettings",
@@ -8049,6 +8049,11 @@
           "description": "A color indicator to appear at the beginning of a list item. Expected value is a valid 3, 4, 6, or 8 character CSS color hex code (e.g., #006fbf).",
           "type": "string"
         },
+        {
+          "name": "first",
+          "type": "boolean",
+          "default": "false"
+        },
         {
           "name": "noPrimaryAction",
           "attribute": "no-primary-action",
@@ -8397,6 +8402,11 @@
           "description": "A color indicator to appear at the beginning of a list item. Expected value is a valid 3, 4, 6, or 8 character CSS color hex code (e.g., #006fbf).",
           "type": "string"
         },
+        {
+          "name": "first",
+          "type": "boolean",
+          "default": "false"
+        },
         {
           "name": "noPrimaryAction",
           "attribute": "no-primary-action",
@@ -8872,6 +8882,11 @@
           "description": "A color indicator to appear at the beginning of a list item. Expected value is a valid 3, 4, 6, or 8 character CSS color hex code (e.g., #006fbf).",
           "type": "string"
         },
+        {
+          "name": "first",
+          "type": "boolean",
+          "default": "false"
+        },
         {
           "name": "noPrimaryAction",
           "attribute": "no-primary-action",
@@ -9177,7 +9192,7 @@
         },
         {
           "name": "d2l-list-add-button-click",
-          "description": "Dispatched when the add button directly after the item is clicked. Event detail includes the key of the item directly above where the add button was clicked."
+          "description": "Dispatched when the add button directly after the item is clicked. Event detail includes position ('before' or 'after') and key.\nThe key belongs to the list item adjacent to where the new item should be positioned.\nThe position represents where the new item should be positioned relative to the item with that key."
         }
       ],
       "slots": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightspace-ui/core",
-  "version": "2.175.0",
+  "version": "2.176.0",
   "description": "A collection of accessible, free, open-source web components for building Brightspace applications",
   "type": "module",
   "repository": "https://github.com/BrightspaceUI/core.git",