fix: Daylight: Search (#1548)

components/calendar/README.md

@@ -8,7 +8,7 @@ The `d2l-calendar` component can be used to display a responsively sized calenda
 
 ## Calendar [d2l-calendar]
 
-<!-- docs: demo live name:d2l-calendar -->
+<!-- docs: demo live name:d2l-calendar display:block -->
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/calendar/calendar.js';

components/inputs/docs/input-search.md

@@ -1,9 +1,12 @@
 # Search Inputs
 
-For text searches use `<d2l-input-search>`, which wraps the native `<input type="search">` element.
+Search inputs allow users to input text, execute a search, and clear results. A search input may be used in conjunction with filters, sort, and/or auto-complete.
 
+<!-- docs: start hidden content -->
 ![example screenshot of search input](../screenshots/search.gif?raw=true)
+<!-- docs: end hidden content -->
 
+<!-- docs: demo -->
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/inputs/input-search.js';
@@ -15,26 +18,56 @@ For text searches use `<d2l-input-search>`, which wraps the native `<input type=
 </d2l-input-search>
 ```
 
-**Properties:**
+## Best Practices
+<!-- docs: start best practices -->
+<!-- docs: start dos -->
+* Specify a label for the search input and include it as part of your design. (e.g. “Search Question Library”) This is typically hidden off-screen, but may be visible when warranted. Use your discretion.
+* Add inline help to communicate when search is limited to specific facets. (e.g. “Search by question text or title”)
+* Use “Search…” (ellipsis inclusive) for placeholder text to distinguish a search input from a straight-up text input.
+* Place the search input in proximity to the content being searched. Best if directly above that content.
+* Persist the search input on-screen if it is a primary or secondary action on the page. Otherwise consider a subtle button to trigger the search input.
+<!-- docs: end dos -->
+
+<!-- docs: start donts -->
+* Don't use placeholder text as a label or to indicate which facets the search is limited to.
+* Don't add a separate control for clearing search results. Use the “Clear Search” button in the search input.
+* Don't rely on search as the only way for users to find things. There are other ways to support finding, including filters, categories, etc.
+<!-- docs: end donts -->
+<!-- docs: end best practices -->
+
+## Search Input [d2l-input-search]
+
+For text searches use `<d2l-input-search>`, which wraps the native `<input type="search">` element.
+
+<!-- docs: demo live name:d2l-input-search -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/inputs/input-search.js';
+</script>
+<script>
+  window.addEventListener('load', function () {
+    document.querySelector('#search').addEventListener('d2l-input-search-searched', (e) => {
+      console.log('searched term:', e.detail.value);
+    });
+  });
+</script>
+<d2l-input-search id="search" label="Search">
+</d2l-input-search>
+```
+
+<!-- docs: start hidden content -->
+### Properties
 
 | Property | Type | Description |
-|--|--|--|
+|---|---|---|
 | `label` | String, required | Accessible label for the input |
 | `disabled` | Boolean | Disables the input |
 | `maxlength` | Number | Imposes an upper character limit |
 | `no-clear` | Boolean | Prevents the "clear" button from appearing |
 | `placeholder` | String, default:`'Search...'` | Placeholder text |
 | `value` | String, default: `''` | Value of the input |
 
-**Accessibility:**
-
-To make your usage of `d2l-input-search` accessible, use the following property when applicable:
-
-| Attribute | Description |
-|--|--|
-| label | **REQUIRED** [Acts as a primary label on the input](https://www.w3.org/WAI/tutorials/forms/labels/). Not visible. |
-
-**Events:**
+### Events
 
 The `d2l-input-search` component dispatches the `d2l-input-search-searched` event when a search is performed:
 
@@ -46,3 +79,12 @@ search.addEventListener('d2l-input-search-searched', (e) => {
 ```
 
 When the input is cleared, the same event will be fired with an empty value.
+<!-- docs: end hidden content -->
+
+### Accessibility
+
+To make your usage of `d2l-input-search` accessible, use the following property when applicable:
+
+| Attribute | Description |
+|---|---|
+| label | **REQUIRED** [Acts as a primary label on the input](https://www.w3.org/WAI/tutorials/forms/labels/). Not visible. |

components/inputs/input-search.js

@@ -9,18 +9,20 @@ import { RtlMixin } from '../../mixins/rtl-mixin.js';
 
 /**
  * This component wraps the native "<input type="search">"" element and is for text searching.
- * @fires d2l-input-search-searched - Dispatched when a search is performed
+ * @fires d2l-input-search-searched - Dispatched when a search is performed. When the input is cleared, this will be fired with an empty value.
  */
 class InputSearch extends LocalizeCoreElement(RtlMixin(LitElement)) {
 
 	static get properties() {
 		return {
 			/**
 			 * Disables the input
+			 * @type {boolean}
 			 */
 			disabled: { type: Boolean },
 			/**
 			 * REQUIRED: Accessible label for the input
+			 * @type {string}
 			 */
 			label: { type: String },
 			/**
@@ -29,18 +31,22 @@ class InputSearch extends LocalizeCoreElement(RtlMixin(LitElement)) {
 			lastSearchValue: { type: String, attribute: false },
 			/**
 			 * Imposes an upper character limit
+			 * @type {number}
 			 */
 			maxlength: { type: Number },
 			/**
 			 * Prevents the "clear" button from appearing
+			 * @type {boolean}
 			 */
 			noClear: { type: Boolean, attribute: 'no-clear' },
 			/**
 			 * Placeholder text (default: "Search...")
+			 * @type {string}
 			 */
 			placeholder: { type: String },
 			/**
 			 * Value of the input
+			 * @type {string}
 			 */
 			value: { type: String }
 		};
@@ -75,6 +81,7 @@ class InputSearch extends LocalizeCoreElement(RtlMixin(LitElement)) {
 		this.value = '';
 	}
 
+	/** @ignore */
 	get lastSearchValue() { return this._lastSearchValue; }
 	set lastSearchValue(val) {}