@brightspace-ui/core 2.24.2 → 2.25.0

package/components/selection/README.md

@@ -8,9 +8,15 @@ The selection components (`d2l-selection-action`, `d2l-selection-input`, `d2l-se
 ![Selection](./screenshots/selection-single.png?raw=true)
 <!-- docs: end hidden content -->
 
+## Use Case
+
+The `d2l-list` already extends `SelectionMixin` and should always be used for lists, however a custom selection control can be defined to enable the use of these selection controls in different semantic contexts or radically different layouts. See [SelectionMixin](#selectionmixin).
+
 ## SelectionMixin
 
-The selection components below work with a component that extends the `SelectionMixin`, which acts like a controller for the checkboxes, radios, actions, etc. The `d2l-selection-input` component must be placed _within_ the component that extends the `SelectionMixin`.  The other selection components may also be placed inside the `SelectionMixin` component, or in the same DOM scope with the `selection-for` attribute set to the id of that component.
+The `SelectionMixin` enables the creation of custom selection control components. The selection components below work with a component that extends the `SelectionMixin` which acts like a controller for the checkboxes, radios, actions and other selection components. The selection components below must be contained within a component that extends the `SelectionMixin`. The `d2l-selection-input` component must be placed _within_ the component that extends the `SelectionMixin`.  The other selection components may also be placed inside the `SelectionMixin` component, or in the same DOM scope with the `selection-for` attribute set to the id of that component.
+
+The `SelectionMixin` defines the `selection-single` attribute that consumers can specify for single selection behaviour.
 
 <!-- docs: demo live name:d2l-demo-selection display:block -->
 ```html
@@ -18,7 +24,7 @@ The selection components below work with a component that extends the `Selection
   import { css, html, LitElement } from 'lit';
   import { SelectionMixin } from '@brightspace-ui/core/components/selection/selection-mixin.js';
 
-  class CustomSelection extends SelectionMixin(LitElement) {
+  class DemoSelection extends SelectionMixin(LitElement) {
     static get styles() {
       return css`
         :host {
@@ -32,7 +38,7 @@ The selection components below work with a component that extends the `Selection
       `;
     }
   }
-  customElements.define('d2l-demo-selection', CustomSelection);
+  customElements.define('d2l-demo-selection', DemoSelection);
 </script>
 <script type="module">
   import '@brightspace-ui/core/components/selection/selection-action.js';
@@ -90,8 +96,6 @@ The selection components below work with a component that extends the `Selection
 </d2l-demo-selection>
 ```
 
-The `d2l-list` already extends `SelectionMixin` and should always be used for lists, however a custom selection control can be easily defined to enable the use of these selection controls in different semantic contexts or radically different layouts. The `SelectionMixin` defines the `selection-single` attribute that consumers can specify for single selection behaviour.
-
 <!-- docs: start hidden content -->
 ### Properties
 
@@ -103,7 +107,7 @@ The `d2l-list` already extends `SelectionMixin` and should always be used for li
 
 ### Usage
 
-The selection components can then be used within the custom selection component as shown above, or the non-`d2l-selection-input` components can be used outside the custom selection component as long as they are in the same DOM scope:
+Define a custom web component that extends the `SelectionMixin`. The selection components can then be used within the custom selection component as shown above, or the non-`d2l-selection-input` components can be used outside the custom selection component as long as they are in the same DOM scope:
 
 ```html
 <div>
@@ -111,17 +115,17 @@ The selection components can then be used within the custom selection component
   <d2l-selection-action selection-for="custom" text="Settings" icon="tier1:gear"></d2l-selection-action>
   <d2l-selection-summary selection-for="custom"></d2l-selection-summary>
 </div>
-<d2l-custom-selection id="custom">
+<d2l-demo-selection id="custom">
   <ul>
     <li><d2l-selection-input key="geo" label="Geography" selected></d2l-selection-input>Geography</li>
     <li><d2l-selection-input key="sci" label="Science"></d2l-selection-input>Science</li>
   </ul>
-</d2l-custom-selection>
+</d2l-demo-selection>
 ```
 
 ## Selection Action [d2l-selection-action]
 
-The `d2l-selection-action` is an optional component that provides a button for actions associated with the selection component (ex. bulk actions). The `requires-selection` attribute may be specified to indicate that the button should be non-interactive if nothing is selected.
+The `d2l-selection-action` is an optional component that provides a button for actions associated with the [selection control](#selectionmixin) (ex. bulk actions). The `requires-selection` attribute may be specified to indicate that the button should be non-interactive if nothing is selected.
 
 <!-- docs: demo live name:d2l-selection-action -->
 ```html
@@ -150,21 +154,19 @@ The `d2l-selection-action` is an optional component that provides a button for a
 
 ## Selection Action Dropdown [d2l-selection-action-dropdown]
 
-The `d2l-selection-action-dropdown` is an optional component that provides a button opener for dropdown content associated with the selection component (ex. bulk actions). The `requires-selection` attribute may be specified to indicate that the opener should be non-interactive if nothing is selected.
+The `d2l-selection-action-dropdown` is an optional component that provides a button opener for dropdown content associated with the [selection control](#selectionmixin) (ex. bulk actions). The `requires-selection` attribute may be specified to indicate that the opener should be non-interactive if nothing is selected.
 
-<!-- docs: demo live name:d2l-selection-action-dropdown autoSize:false size:medium align:baseline -->
+<!-- docs: demo live name:d2l-selection-action-dropdown align:baseline -->
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/dropdown/dropdown-menu.js';
   import '@brightspace-ui/core/components/menu/menu.js';
-  import '@brightspace-ui/core/components/menu/menu-item.js';
   import '@brightspace-ui/core/components/selection/selection-action-dropdown.js';
 </script>
 <d2l-selection-action-dropdown text="Actions" requires-selection>
   <d2l-dropdown-menu>
     <d2l-menu label="Actions">
-      <d2l-menu-item text="Action 1"></d2l-menu-item>
-      <d2l-menu-item text="Action 2"></d2l-menu-item>
+      <!-- This is where you add instances of <d2l-selection-action-menu-item>. -->
     </d2l-menu>
   </d2l-dropdown-menu>
 </d2l-selection-action-dropdown>
@@ -182,7 +184,7 @@ The `d2l-selection-action-dropdown` is an optional component that provides a but
 
 ## Selection Action Menu Item [d2l-selection-action-menu-item]
 
-The `d2l-selection-action-menu-item` is an optional component that is a menu item for actions associated with the selection component (ex. bulk actions). The `requires-selection` attribute may be specified to indicate that the menu item should be non-interactive if nothing is selected. This component enables the app to define an opener that is enabled regardless of the selection state, while having a menu containing one or more menu items that `requires-selection`.
+The `d2l-selection-action-menu-item` is an optional component that is a menu item for actions associated with the [selection control](#selectionmixin) (ex. bulk actions). The `requires-selection` attribute may be specified to indicate that the menu item should be non-interactive if nothing is selected. This component enables the app to define an opener that is enabled regardless of the selection state, while having a menu containing one or more menu items that `requires-selection`.
 
 <!-- docs: demo live name:d2l-selection-action-menu-item autoSize:false size:medium align:baseline -->
 ```html
@@ -220,7 +222,11 @@ The `d2l-selection-action-menu-item` is an optional component that is a menu ite
 
 ## Selection Input [d2l-selection-input]
 
-The `d2l-selection-input` is a required component in selection controls - without it, there wouldn't be anything for the user to select! Note: `d2l-list-item` already provides a selection input for selectable list items. If `d2l-selection-input` is placed within a selection control that specifies `selection-single`, then radios will be rendered instead of checkboxes.
+The `d2l-selection-input` is a required component in selection controls - without it, there wouldn't be anything for the user to select! This component must be placed _within_ the [selection control](#selectionmixin).
+
+If `d2l-selection-input` is placed within a selection control that specifies `selection-single`, then radios will be rendered instead of checkboxes.
+
+Note: `d2l-list-item` already provides a selection input for selectable list items.
 
 <!-- docs: demo live name:d2l-selection-input display:block -->
 ```html
@@ -247,6 +253,7 @@ The `d2l-selection-input` is a required component in selection controls - withou
   <ul>
     <li><d2l-selection-input key="geo" label="Geography" selected></d2l-selection-input>Geography</li>
     <li><d2l-selection-input key="sci" label="Science"></d2l-selection-input>Science</li>
+    <li><d2l-selection-input key="mat" label="Math"></d2l-selection-input>Math</li>
   </ul>
 </d2l-demo-selection>
 ```
@@ -274,9 +281,9 @@ Either `label` or `labelled-by` is **required**.
 
 ## Select All [d2l-selection-select-all]
 
-The `d2l-selection-select-all` is an optional component that provides a checkbox for bulk selecting the selectable elements within the selection control. Its state will also be automatically updated when the state of the selectable elements change.
+The `d2l-selection-select-all` is an optional component that provides a checkbox for bulk selecting the selectable elements within the [selection control](#selectionmixin). Its state will also be automatically updated when the state of the selectable elements change.
 
-In the example below, setting `selection-for` to `other-list` demonstrates the ability to use `d2l-selection-select-all` for `d2l-select-input` outside of the custom selection element.
+The `d2l-selection-select-all` component may be placed inside the selection control, or in the same DOM scope with the `selection-for` attribute set to the id of that component. In the example below, setting `selection-for` to `other-list` demonstrates the ability to use `d2l-selection-select-all` from outside of the selection control component.
 
 <!-- docs: demo live name:d2l-selection-select-all display:block -->
 ```html
@@ -288,6 +295,13 @@ In the example below, setting `selection-for` to `other-list` demonstrates the a
 </script>
 <!-- docs: start hidden content -->
 <style>
+  .container {
+    justify-content: center;
+  }
+  #other-list {
+    padding-top: 2.1rem;
+    margin-left: 5rem;
+  }
   ul {
     margin: 0;
     padding: 0;
@@ -304,27 +318,41 @@ In the example below, setting `selection-for` to `other-list` demonstrates the a
   d2l-selection-input {
     margin-right: 10px;
   }
-  #other-list {
-    padding-top: 1rem;
+  @media only screen and (max-width: 350px) {
+    body {
+      overflow-y: scroll;
+    }
+    .container {
+      align-items: flex-start;
+      flex-direction: column;
+      margin-right: 15px;
+    }
+    #other-list {
+      margin-left: 0;   
+    }
   }
 </style>
 <!-- docs: end hidden content -->
-<d2l-demo-selection>
-  <div>
-    <d2l-selection-select-all></d2l-selection-select-all>
-    <d2l-selection-action text="Bookmark" icon="tier1:bookmark-hollow" requires-selection></d2l-selection-action>
-  </div>
-  <ul>
-    <li><d2l-selection-input key="geo" label="Geography"></d2l-selection-input>List 1 item 1</li>
-    <li><d2l-selection-input key="sci" label="Science"></d2l-selection-input>List 1 item 2</li>
-  </ul>
-</d2l-demo-selection>
-<d2l-demo-selection id="other-list">
-  <ul>
-    <li><d2l-selection-input key="geo" label="Geography"></d2l-selection-input>List 2 item 1</li>
-    <li><d2l-selection-input key="sci" label="Science"></d2l-selection-input>List 2 item 2</li>
-  </ul>
-</d2l-demo-selection>
+<div class="container">
+  <d2l-demo-selection>
+    <div>
+      <d2l-selection-select-all></d2l-selection-select-all>
+      <d2l-selection-action text="Bookmark" icon="tier1:bookmark-hollow" requires-selection></d2l-selection-action>
+    </div>
+    <ul>
+      <li><d2l-selection-input key="geo" label="Geography"></d2l-selection-input>Geography</li>
+      <li><d2l-selection-input key="sci" label="Science"></d2l-selection-input>Science</li>
+      <li><d2l-selection-input key="mat" label="Math" disabled></d2l-selection-input>Math</li>
+    </ul>
+  </d2l-demo-selection>
+  <d2l-demo-selection id="other-list">
+    <ul>
+      <li><d2l-selection-input key="ear" label="Earth"></d2l-selection-input>Earth</li>
+      <li><d2l-selection-input key="mar" label="Mars"></d2l-selection-input>Mars</li>
+      <li><d2l-selection-input key="jup" label="Jupiter"></d2l-selection-input>Jupiter</li>
+    </ul>
+  </d2l-demo-selection>
+</div>
 ```
 
 <!-- docs: start hidden content -->
@@ -338,9 +366,9 @@ In the example below, setting `selection-for` to `other-list` demonstrates the a
 
 ## Selection Summary [d2l-selection-summary]
 
-The `d2l-selection-summary` is an optional component that shows a simple count of the selected items within the selection control.
+The `d2l-selection-summary` is an optional component that shows a simple count of the selected items within the [selection control](#selectionmixin).
 
-In the example below, setting `selection-for` to `other-list` demonstrates the ability to use `d2l-selection-summary` for `d2l-select-input` outside of the custom selection element.
+The `d2l-selection-summary` component may be placed inside the selection control, or in the same DOM scope with the `selection-for` attribute set to the id of that component. In the example below, setting `selection-for` to `other-list` demonstrates the ability to use `d2l-selection-summary` from outside of the selection control component.
 
 <!-- docs: demo live name:d2l-selection-summary display:block -->
 ```html
@@ -351,6 +379,14 @@ In the example below, setting `selection-for` to `other-list` demonstrates the a
 </script>
 <!-- docs: start hidden content -->
 <style>
+  .container {
+    display: flex;
+    justify-content: center;
+  }
+  #other-list {
+    padding-top: 1rem;
+    margin-left: 5rem;
+  }
   ul {
     margin: 0;
     padding: 0;
@@ -367,27 +403,40 @@ In the example below, setting `selection-for` to `other-list` demonstrates the a
   d2l-selection-input {
     margin-right: 10px;
   }
-  #other-list {
-    padding-top: 1rem;
+  @media only screen and (max-width: 350px) {
+    body {
+      overflow-y: scroll;
+    }
+    .container {
+      align-items: flex-start;
+      flex-direction: column;
+    }
+    #other-list {
+      margin-left: 0;
+    }
   }
 </style>
 <!-- docs: end hidden content -->
-<d2l-demo-selection>
-  <div>
-    <d2l-selection-action text="Bookmark" icon="tier1:bookmark-hollow" requires-selection></d2l-selection-action>
-    <d2l-selection-summary></d2l-selection-summary>
-  </div>
-  <ul>
-    <li><d2l-selection-input key="geo" label="Geography"></d2l-selection-input>List 1 item 1</li>
-    <li><d2l-selection-input key="sci" label="Science"></d2l-selection-input>List 1 item 2</li>
-  </ul>
-</d2l-demo-selection>
-<d2l-demo-selection id="other-list">
-  <ul>
-    <li><d2l-selection-input key="geo" label="Geography"></d2l-selection-input>List 2 item 1</li>
-    <li><d2l-selection-input key="sci" label="Science"></d2l-selection-input>List 2 item 2</li>
-  </ul>
-</d2l-demo-selection>
+<div class="container">
+  <d2l-demo-selection>
+    <div>
+      <d2l-selection-action text="Bookmark" icon="tier1:bookmark-hollow" requires-selection></d2l-selection-action>
+      <d2l-selection-summary></d2l-selection-summary>
+    </div>
+    <ul>
+      <li><d2l-selection-input key="geo" label="Geography"></d2l-selection-input>Geography</li>
+      <li><d2l-selection-input key="sci" label="Science"></d2l-selection-input>Science</li>
+      <li><d2l-selection-input key="mat" label="Math" disabled></d2l-selection-input>Math</li>
+    </ul>
+  </d2l-demo-selection>
+  <d2l-demo-selection id="other-list">
+    <ul>
+      <li><d2l-selection-input key="ear" label="Earth"></d2l-selection-input>Earth</li>
+        <li><d2l-selection-input key="mar" label="Mars"></d2l-selection-input>Mars</li>
+        <li><d2l-selection-input key="jup" label="Jupiter"></d2l-selection-input>Jupiter</li>
+    </ul>
+  </d2l-demo-selection>
+</div>
 ```
 
 <!-- docs: start hidden content -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightspace-ui/core",
-  "version": "2.24.2",
+  "version": "2.25.0",
   "description": "A collection of accessible, free, open-source web components for building Brightspace applications",
   "type": "module",
   "repository": "https://github.com/BrightspaceUI/core.git",
@@ -44,7 +44,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@babel/eslint-parser": "^7",
-    "@brightspace-ui/stylelint-config": "^0.4",
+    "@brightspace-ui/stylelint-config": "^0.5",
     "@open-wc/testing": "^3",
     "@web/dev-server": "^0.1",
     "@web/test-runner": "^0.13",