@brightspace-ui/core 3.25.1 → 3.26.0

package/components/button/README.md

@@ -53,16 +53,6 @@ The `d2l-button` element can be used just like the native button element, but al
 | `primary` | Boolean | Styles the button as a primary button |
 <!-- docs: end hidden content -->
 
-### Accessibility Properties
-
-To make your `d2l-button` accessible, use the following properties when applicable:
-
-| Attribute | Description |
-|---|---|
-| `aria-expanded` | [Indicate expansion state of a collapsible element](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-expanded). Example: [d2l-more-less](https://github.com/BrightspaceUI/core/blob/f9f30d0975ee5a8479263a84541fc3b781e8830f/components/more-less/more-less.js#L158). |
-| `aria-haspopup` | [Indicate clicking the button opens a menu](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-haspopup). Example: [d2l-dropdown](https://github.com/BrightspaceUI/core/blob/main/components/dropdown/dropdown-opener-mixin.js#L46). |
-| `description` | Use when text on button does not provide enough context. |
-
 ## Subtle Button [d2l-button-subtle]
 
 The `d2l-button-subtle` element can be used just like the native `button`, but for advanced or de-emphasized actions.
@@ -91,16 +81,6 @@ The `d2l-button-subtle` element can be used just like the native `button`, but f
 | `icon-right` | Boolean | Render the icon on the right of the button |
 <!-- docs: end hidden content -->
 
-### Accessibility Properties
-
-To make your `d2l-button-subtle` accessible, use the following properties when applicable:
-
-| Attribute | Description |
-|---|---|
-| `aria-expanded` | [Indicate expansion state of a collapsible element](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-expanded). Example: [d2l-more-less](https://github.com/BrightspaceUI/core/blob/f9f30d0975ee5a8479263a84541fc3b781e8830f/components/more-less/more-less.js#L158). |
-| `aria-haspopup` | [Indicate clicking the button opens a menu](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-haspopup). Example: [d2l-dropdown](https://github.com/BrightspaceUI/core/blob/main/components/dropdown/dropdown-opener-mixin.js#L46). |
-| `description` | Use when text on button does not provide enough context. |
-
 ### Subtle Button with Custom Icon
 
 <!-- docs: demo code  -->
@@ -145,18 +125,6 @@ The `d2l-button-icon` element can be used just like the native `button`, for ins
 | `translucent` | Boolean | Indicates to display translucent (ex. on rich backgrounds) |
 <!-- docs: end hidden content -->
 
-### Accessibility Properties
-
-To make your `d2l-button-icon` accessible, use the following properties when applicable:
-
-| Attribute | Description |
-|---|---|
-| `text` | **REQUIRED**. Acts as a primary label and tooltip. |
-| `aria-expanded` | [Indicate expansion state of a collapsible element](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-expanded). Example: [d2l-more-less](https://github.com/BrightspaceUI/core/blob/f9f30d0975ee5a8479263a84541fc3b781e8830f/components/more-less/more-less.js#L158). |
-| `aria-haspopup` | [Indicate clicking the button opens a menu](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-haspopup). Example: [d2l-dropdown](https://github.com/BrightspaceUI/core/blob/main/components/dropdown/dropdown-opener-mixin.js#L46). |
-| `aria-label` | Acts as a primary label. If `text` AND `aria-label` are provided, `aria-label` is used as the primary label, `text` is used as the tooltip. |
-| `description` | Use when text on button does not provide enough context. |
-
 ### Icon Button with Custom Icon
 
 <!-- docs: demo code  -->
@@ -177,7 +145,7 @@ To make your `d2l-button-icon` accessible, use the following properties when app
 
 ## Add Button [d2l-button-add]
 
-The `d2l-button-add` element is for quickly adding new items inline (for example in a list).
+The `d2l-button-add` is for quickly adding new items at a specific location, such as when adding items to a curated list. Since the Add button is meant to be subtle, it should always be used in combination with more obvious methods to add items (like a menu or primary button).
 
 <!-- docs: demo code properties name:d2l-button-add display:block autoSize:false size:xsmall -->
 ```html
@@ -198,7 +166,62 @@ The `d2l-button-add` element is for quickly adding new items inline (for example
 
 ## Floating Buttons [d2l-floating-buttons]
 
-See [floating buttons](https://github.com/BrightspaceUI/core/tree/main/components/button/floating-buttons.md).
+Floating workflow buttons `<d2l-floating-buttons>` cause buttons to float or 'dock' to the bottom of the viewport when they would otherwise be below the bottom of the viewport. When their normal position becomes visible, they will undock.
+
+The best time to use floating workflow buttons is when users need immediate access to the buttons without scrolling. An example is a long or complex form page where it's common for users to make frequent isolated edits rather than sequentially completing the form.
+
+<!-- docs: demo code properties name:d2l-floating-buttons autoSize:false display:block size:xlarge -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/button/floating-buttons.js';
+  import '@brightspace-ui/core/components/button/button.js';
+</script>
+<!-- docs: start hidden content -->
+<style>
+  .d2l-typography p {
+    margin: 0.5rem;
+  }
+  .content-placeholder {
+    align-items: center;
+    background-color: var(--d2l-color-regolith);
+    border: 2px dashed lightgrey;
+    border-radius: 8px;
+    display: flex;
+    height: 600px;
+    justify-content: center;
+    width: 100%;
+  }
+  .empty-space {
+    height: 5rem;
+  }
+</style>
+<!-- docs: end hidden content -->
+<div class="content-placeholder d2l-body-compact">
+  Scroll to unstick
+</div>
+<d2l-floating-buttons>
+  <d2l-button primary>Primary</d2l-button>
+  <d2l-button>Secondary</d2l-button>
+</d2l-floating-buttons>
+<div class="empty-space"></div>
+```
+
+## Accessibility
+
+Daylight buttons rely on standard button semantics to ensure a smooth experience for all assistive technologies, but there are a few interesting details to note:
+
+* If the button's context is implied by visual layout, then `description` can be used to add missing context
+  * Example: if multiple page sections have an Edit button relying on visual layout to indicate which section it edits, there could be extra information in the `description` to help differentiate the Edit buttons for non-sighted users
+
+* If expanding other content in a dropdown, use the [Dropdown](../../components/dropdown) component; if building custom expand/collapse behaviour, be sure to use [`aria-expanded`](https://www.w3.org/TR/wai-aria/states_and_properties#aria-expanded) and [`aria-haspopup`](https://www.w3.org/TR/wai-aria/states_and_properties#aria-haspopup) attributes in accordance with best practices.
+
+* Disabled buttons are normally not focusable as per web standards, but if the disabled state needs explaining you can use `disabled-tooltip` to provide an explanation that appears in a [tooltip](../../components/tooltip) via [aria-describedby](https://www.w3.org/TR/wai-aria/states_and_properties#aria-describedby)
+
+* For [Icon Buttons](#d2l-button-icon) where there is no visible label, `text` will be displayed in a tooltip
+  * If both `text` and `aria-label` are used, then `aria-label` will be used as the primary label while `text` will be used in a [tooltip](../../components/tooltip)
+
+* [Floating Buttons](#d2l-floating-buttons) maintain their position in the document's structure, despite sticking to the bottom of the viewport, so the tab order is unaffected and the effect is imperceptible to screen reader users
+  * Be cautious when using `always-float`, since screen magnifier users may find it difficult to locate the buttons at the bottom of a large viewport
 
 <!-- docs: start hidden content -->
 ## Future Improvements

package/components/button/button-add.js

@@ -28,7 +28,7 @@ class ButtonAdd extends RtlMixin(PropertyRequiredMixin(FocusMixin(LocalizeCoreEl
 			 */
 			mode: { type: String, reflect: true },
 			/**
-			 * 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.
+			 * ACCESSIBILITY: 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 }

package/components/button/button-icon.js

@@ -20,7 +20,7 @@ class ButtonIcon extends ThemeMixin(ButtonMixin(VisibleOnAncestorMixin(RtlMixin(
 	static get properties() {
 		return {
 			/**
-			 * A description to be added to the button for accessibility when text on button does not provide enough context
+			 * ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context
 			 * @type {string}
 			 */
 			description: { type: String },
@@ -38,7 +38,7 @@ class ButtonIcon extends ThemeMixin(ButtonMixin(VisibleOnAncestorMixin(RtlMixin(
 			icon: { type: String, reflect: true },
 
 			/**
-			 * REQUIRED: Accessible text for the button
+			 * ACCESSIBILITY: REQUIRED: Accessible text for the button
 			 * @type {string}
 			 */
 			text: { type: String, reflect: true },

package/components/button/button-move.js

@@ -44,7 +44,7 @@ class ButtonMove extends ThemeMixin(FocusMixin(RtlMixin(LitElement))) {
 			// eslint-disable-next-line lit/no-native-attributes
 			autofocus: { type: Boolean, reflect: true },
 			/**
-			 * A description to be added to the button for accessibility when text on button does not provide enough context
+			 * ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context
 			 * @type {string}
 			 */
 			description: { type: String },
@@ -79,7 +79,7 @@ class ButtonMove extends ThemeMixin(FocusMixin(RtlMixin(LitElement))) {
 			 */
 			disabledUp: { type: Boolean, attribute: 'disabled-up', reflect: true },
 			/**
-			 * REQUIRED: Accessible text for the button
+			 * ACCESSIBILITY: REQUIRED: Accessible text for the button
 			 * @type {string}
 			 */
 			text: { type: String, reflect: true }

package/components/button/button-subtle.js

@@ -18,7 +18,7 @@ class ButtonSubtle extends ButtonMixin(LitElement) {
 	static get properties() {
 		return {
 			/**
-			 * A description to be added to the button for accessibility when text on button does not provide enough context
+			 * ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context
 			 * @type {string}
 			 */
 			description: { type: String },
@@ -48,7 +48,7 @@ class ButtonSubtle extends ButtonMixin(LitElement) {
 			slim: { type: Boolean, reflect: true },
 
 			/**
-			 * REQUIRED: Text for the button
+			 * ACCESSIBILITY: REQUIRED: Text for the button
 			 * @type {string}
 			 */
 			text: { type: String, reflect: true },

package/components/button/button.js

@@ -16,7 +16,7 @@ class Button extends ButtonMixin(LitElement) {
 	static get properties() {
 		return {
 			/**
-			 * A description to be added to the button for accessibility when text on button does not provide enough context
+			 * ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context
 			 * @type {string}
 			 */
 			description: { type: String },

package/custom-elements.json

@@ -350,7 +350,7 @@
       "attributes": [
         {
           "name": "text",
-          "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.",
+          "description": "ACCESSIBILITY: 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"
         },
         {
@@ -364,7 +364,7 @@
         {
           "name": "text",
           "attribute": "text",
-          "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.",
+          "description": "ACCESSIBILITY: 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"
         },
         {
@@ -414,7 +414,7 @@
       "attributes": [
         {
           "name": "description",
-          "description": "A description to be added to the button for accessibility when text on button does not provide enough context",
+          "description": "ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context",
           "type": "string"
         },
         {
@@ -429,7 +429,7 @@
         },
         {
           "name": "text",
-          "description": "REQUIRED: Accessible text for the button",
+          "description": "ACCESSIBILITY: REQUIRED: Accessible text for the button",
           "type": "string"
         },
         {
@@ -454,7 +454,7 @@
         {
           "name": "description",
           "attribute": "description",
-          "description": "A description to be added to the button for accessibility when text on button does not provide enough context",
+          "description": "ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context",
           "type": "string"
         },
         {
@@ -472,7 +472,7 @@
         {
           "name": "text",
           "attribute": "text",
-          "description": "REQUIRED: Accessible text for the button",
+          "description": "ACCESSIBILITY: REQUIRED: Accessible text for the button",
           "type": "string"
         },
         {
@@ -520,7 +520,7 @@
       "attributes": [
         {
           "name": "description",
-          "description": "A description to be added to the button for accessibility when text on button does not provide enough context",
+          "description": "ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context",
           "type": "string"
         },
         {
@@ -555,7 +555,7 @@
         },
         {
           "name": "text",
-          "description": "REQUIRED: Accessible text for the button",
+          "description": "ACCESSIBILITY: REQUIRED: Accessible text for the button",
           "type": "string"
         }
       ],
@@ -563,7 +563,7 @@
         {
           "name": "description",
           "attribute": "description",
-          "description": "A description to be added to the button for accessibility when text on button does not provide enough context",
+          "description": "ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context",
           "type": "string"
         },
         {
@@ -605,7 +605,7 @@
         {
           "name": "text",
           "attribute": "text",
-          "description": "REQUIRED: Accessible text for the button",
+          "description": "ACCESSIBILITY: REQUIRED: Accessible text for the button",
           "type": "string"
         }
       ],
@@ -623,7 +623,7 @@
       "attributes": [
         {
           "name": "description",
-          "description": "A description to be added to the button for accessibility when text on button does not provide enough context",
+          "description": "ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context",
           "type": "string"
         },
         {
@@ -638,7 +638,7 @@
         },
         {
           "name": "text",
-          "description": "REQUIRED: Text for the button",
+          "description": "ACCESSIBILITY: REQUIRED: Text for the button",
           "type": "string"
         },
         {
@@ -669,7 +669,7 @@
         {
           "name": "description",
           "attribute": "description",
-          "description": "A description to be added to the button for accessibility when text on button does not provide enough context",
+          "description": "ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context",
           "type": "string"
         },
         {
@@ -687,7 +687,7 @@
         {
           "name": "text",
           "attribute": "text",
-          "description": "REQUIRED: Text for the button",
+          "description": "ACCESSIBILITY: REQUIRED: Text for the button",
           "type": "string"
         },
         {
@@ -736,7 +736,7 @@
       "attributes": [
         {
           "name": "description",
-          "description": "A description to be added to the button for accessibility when text on button does not provide enough context",
+          "description": "ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context",
           "type": "string"
         },
         {
@@ -761,7 +761,7 @@
         {
           "name": "description",
           "attribute": "description",
-          "description": "A description to be added to the button for accessibility when text on button does not provide enough context",
+          "description": "ACCESSIBILITY: A description to be added to the button for accessibility when text on button does not provide enough context",
           "type": "string"
         },
         {

package/package.json

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

package/components/button/floating-buttons.md

@@ -1,60 +0,0 @@
-# Floating Buttons
-
-Floating workflow buttons behavior can be added by using the `<d2l-floating-buttons>` custom element. When the normal position of the workflow buttons is below the bottom edge of the viewport, they will dock at the bottom edge. When the normal position becomes visible, they will undock.
-
-<!-- docs: demo name:d2l-floating-buttons autoSize:false display:block size:medium -->
-```html
-<script type="module">
-  import '@brightspace-ui/core/components/button/floating-buttons.js';
-  import '@brightspace-ui/core/components/button/button.js';
-</script>
-<style>
-  .d2l-typography p {
-    margin: 1rem;
-  }
-  d2l-button { 
-    margin-left: 0.5rem;
-  }
-</style>
-<p>
-  Lorem ipsum dolor sit amet, consectetur adipisicing elit. Adipisci repellat cum totam! Enim, sunt. Numquam voluptate, velit quisquam ipsa molestias laudantium odit reiciendis nisi corporis voluptatibus, voluptatum sunt natus, accusantium magnam consequatur fugit officiis minima voluptatem consequuntur nam, earum necessitatibus! Cupiditate ullam repellendus, eius iure voluptas at commodi consectetur, quia, adipisci possimus, ex mollitia. Labore harum error consectetur officiis aut optio, temporibus iste nobis ducimus cumque laudantium rem pariatur. Ut repudiandae id, consequuntur quasi quis pariatur autem corporis perferendis facilis eius similique voluptatibus iusto deleniti odio officia numquam tenetur excepturi, aspernatur sunt minima aut fugiat ipsam.
-</p>
-<d2l-floating-buttons always-float>
-  <d2l-button primary>Primary</d2l-button>
-  <d2l-button>Secondary</d2l-button>
-</d2l-floating-buttons>
-```
-
-## Floating Buttons [d2l-floating-buttons]
-
-<!-- docs: demo code properties name:d2l-floating-buttons autoSize:false display:block size:medium -->
-```html
-<script type="module">
-  import '@brightspace-ui/core/components/button/floating-buttons.js';
-  import '@brightspace-ui/core/components/button/button.js';
-</script>
-<style>
-  .d2l-typography p {
-    margin: 1rem;
-  }
-
-  d2l-button { 
-    margin-left: 0.5rem;
-  }
-</style>
-<p>
-  Lorem ipsum dolor sit amet, consectetur adipisicing elit. Adipisci repellat cum totam! Enim, sunt. Numquam voluptate, velit quisquam ipsa molestias laudantium odit reiciendis nisi corporis voluptatibus, voluptatum sunt natus, accusantium magnam consequatur fugit officiis minima voluptatem consequuntur nam, earum necessitatibus! Cupiditate ullam repellendus, eius iure voluptas at commodi consectetur, quia, adipisci possimus, ex mollitia. Labore harum error consectetur officiis aut optio, temporibus iste nobis ducimus cumque laudantium rem pariatur. Ut repudiandae id, consequuntur quasi quis pariatur autem corporis perferendis facilis eius similique voluptatibus iusto deleniti odio officia numquam tenetur excepturi, aspernatur sunt minima aut fugiat ipsam. Ea nesciunt, amet fugit facere similique dolor nam tempora perferendis aut fugiat non, ex pariatur excepturi odio aspernatur libero saepe ducimus rem magni cumque. Laboriosam nisi fuga accusantium quos qui? Maiores ratione aliquam eos odio eius molestiae nesciunt exercitationem dolor perspiciatis quam. Necessitatibus rem nihil ad culpa, tenetur iusto consectetur rerum, delectus neque? Error, quas, eaque! Quibusdam voluptas expedita possimus consequatur accusantium distinctio, esse quisquam, ipsa blanditiis, officia perferendis et? Iste, nam optio vero earum tenetur voluptatibus modi a, odit aliquid eos corporis nulla saepe vel neque voluptate ratione, facilis quo sed nisi voluptates nostrum dolor. Non mollitia dignissimos laudantium quos libero nisi, nobis harum, asperiores soluta reprehenderit doloremque ipsa id unde voluptates beatae deserunt. Minima repellendus ipsam molestias veritatis pariatur nobis nihil, alias quasi, esse, aspernatur saepe beatae, hic consequatur. Sit sequi, libero quisquam quibusdam fuga tempore ab molestiae praesentium, necessitatibus, vero odio ullam qui non totam voluptas reprehenderit ad neque voluptate. Nam atque impedit ducimus, dolore reiciendis delectus inventore beatae cumque. Magni, id quos officiis soluta consequatur nam quis, modi fugit adipisci vel autem dolorum iusto cumque, libero reprehenderit amet doloremque voluptatem sunt sapiente reiciendis omnis, similique nulla enim. Autem repellendus, illo eveniet recusandae quae quibusdam itaque, delectus, consequatur provident vitae vero magnam repudiandae fugit, placeat sapiente! Omnis, possimus natus.
-</p>
-<d2l-floating-buttons always-float>
-  <d2l-button primary>Primary</d2l-button>
-  <d2l-button>Secondary</d2l-button>
-</d2l-floating-buttons>
-```
-
-<!-- docs: start hidden content -->
-### Properties:
-
-| Property | Type | Description |
-|--|--|--|
-| `always-float` | Boolean | Indicates to display buttons as always floating |
-<!-- docs: end hidden content -->