Skip to content

Commit

Permalink
fix: Daylight: Text & Textarea (#1569)
Browse files Browse the repository at this point in the history
  • Loading branch information
@margaree
margaree authored Aug 5, 2021
1 parent 2018c62 commit 16146b7
Show file tree
Hide file tree
Showing 7 changed files with 285 additions and 148 deletions.
4 changes: 1 addition & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,11 @@ npm install @brightspace-ui/core
* [Inputs](components/inputs/):
* [Checkbox](components/inputs/docs/input-checkbox.md): checkbox components and styles
* [Date and time](components/inputs/docs/input-date-time.md): date and time picker components including ranges
* [Number](components/inputs/docs/input-number.md): number input component
* [Percent](components/inputs/docs/input-percent.md): percent input component
* [Number](components/inputs/docs/input-numeric.md): numeric input components
* [Radio](components/inputs/docs/input-radio.md): radio input styles
* [Search](components/inputs/docs/input-search.md): search input component
* [Select styles](components/inputs/docs/input-select-styles.md): select input styles
* [Text](components/inputs/docs/input-text.md): text input component and styles
* [Text Area](components/inputs/docs/input-textarea.md): multi-line text component
* [Links](components/link/): link component and styles
* [List](components/list/): list and list-item components
* [Loading Spinner](components/loading-spinner/): loading-spinner components
Expand Down
3 changes: 1 addition & 2 deletions components/inputs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,7 @@ There are various input components available:
- [Radio Buttons (input-radio-*)](docs/input-radio.md)
- [Search (input-search)](docs/input-search.md)
- [Select Lists (input-select-styles)](docs/input-select-styles.md)
- [Text (input-text, input-styles)](docs/input-text.md)
- [Text Areas (input-textarea)](docs/input-textarea.md)
- [Text (input-text, input-styles, input-textarea)](docs/input-text.md)

## Labelling Inputs

Expand Down
226 changes: 199 additions & 27 deletions components/inputs/docs/input-text.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,82 @@
# Text Inputs
# Text & Textarea Inputs

Text inputs allow users to input, edit, and select text.

<!-- docs: demo -->
```html
<script type="module">
import '@brightspace-ui/core/components/inputs/input-text.js';
import '@brightspace-ui/core/components/inputs/input-textarea.js';
</script>
<style>
div {
width: 100%;
}
d2l-input-text {
padding-bottom: 1rem;
}
</style>
<div>
<d2l-input-text label="Name"></d2l-input-text>
<d2l-input-textarea label="Description" max-rows="4" rows="4"></d2l-input-textarea>
</div>
```

## Best Practices
<!-- docs: start best practices -->
<!-- docs: start dos -->
* Make sure you include an obvious indication of what the field is for. Usually this means a label.
* Design the length of the text input to give the user a scent of how long the expected data should be.
* Ensure the label remains visible when a user focuses on the input using their mobile device. Often this means using a top-aligned label, but a left-aligned label with a very short text input can work also.
* Placeholder text is inaccessible so only use it for decorative or supporting text.
<!-- docs: end dos -->

<!-- docs: start donts -->
* Don’t use placeholder text as the label.
* Don’t use placeholder text if it is redundant (ie: “Click to start typing”)
* Don’t use placeholder text to communicate the required format of the input (ie: “YY/MM/DD”). Use help or label text for this.
* Don’t use different font sizes. Text should always be Compact.
<!-- docs: end donts -->
<!-- docs: end best practices -->

## Accessibility

Due to widespread popularity, users have a strong association that placeholder text in text inputs should appear “light gray” compared to active text colour. This has been confirmed in our own usability tests; any text that appears dark enough to pass WCAG AA colour contrast tests is also interpreted as “editable” by users.

Therefore in text inputs, placeholder text is a light colour (Mica), which fails colour contrast. Because of this, placeholder text should be used sparingly, and never be used to communicate crucial information unless that information is also made available to screen readers via an equivalent experience (hidden label, etc). Text which is decorative or supplemental is okay, as is using a hidden label which provides the same information.

## Text Input [d2l-input-text]

The `<d2l-input-text>` element is a simple wrapper around the native `<input type="text">` tag. It's intended primarily for inputting generic text, email addresses and URLs.

<!-- docs: start hidden content -->
![example screenshot of text input](../screenshots/text.gif?raw=true)
<!-- docs: end hidden content -->

<!-- docs: demo live name:d2l-input-text -->
```html
<script type="module">
import '@brightspace-ui/core/components/inputs/input-text.js';
</script>
<d2l-input-text
label="Label"
placeholder="Enter some text"
value="hello"></d2l-input-text>
<script>
window.addEventListener('load', function () {
var input = document.querySelector('#text');
input.addEventListener('change', (e) => {
console.log('input-text change: ', input.value);
});
input.addEventListener('input', (e) => {
console.log('input-text input: ', input.value);
});
});
</script>
<d2l-input-text id="text" label="Label"></d2l-input-text>
```

**Properties:**
<!-- docs: start hidden content -->
### Properties

| Property | Type | Description |
|--|--|--|
|---|---|---|
| `label` | String, required | Label for the input |
| `aria-haspopup` | String | Indicates that the input has a popup menu |
| `aria-invalid` | String | Indicates that the input value is invalid |
Expand Down Expand Up @@ -45,12 +104,34 @@ The `<d2l-input-text>` element is a simple wrapper around the native `<input typ
| `unit` | String | Unit associated with the input value, displayed next to input and announced as part of the label |
| `value` | String, default: `''` | Value of the input |

**Accessibility:**
### Events

The `d2l-input-text` dispatches the `change` event when an alteration to the value is committed (typically after focus is lost) by the user. To be notified immediately of changes made by the user, use the `input` event.

```javascript
// dispatched when value changes are committed
input.addEventListener('change', (e) => {
console.log(input.value);
});

// dispatched whenever value changes occur
input.addEventListener('input', (e) => {
console.log(input.value);
});
```

### Slots

* `left`: Slot within the input on the left side. Useful for an `icon` or `button-icon`.
* `right`: Slot within the input on the right side. Useful for an `icon` or `button-icon`.
<!-- docs: end hidden content -->

### Accessibility Properties

To make your usage of `d2l-input-text` accessible, use the following properties when applicable:

| Attribute | Description |
|--|--|
|---|---|
| `aria-haspopup` | [Indicate clicking the input opens a menu](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-haspopup). |
| `aria-invalid` | [Indicate that the input value is invalid](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-invalid) |
| `aria-label` | Use when `label` does not provide enough context. Only applies if no `label-hidden`. |
Expand All @@ -60,43 +141,134 @@ To make your usage of `d2l-input-text` accessible, use the following properties
| `unit` | Use to render the unit (offscreen) as part of the label. |
| `title` | Text for additional screen reader and mouseover context |

**Events:**
## Applying styles to native text input

The `d2l-input-text` dispatches the `change` event when an alteration to the value is committed (typically after focus is lost) by the user. To be notified immediately of changes made by the user, use the `input` event.
As an alternative to using the `<d2l-input-text>` custom element, you can style a native text input inside your own element. Import `input-styles.js` and apply the `d2l-input` CSS class to the input:

**Slots:**
* `left`: Slot within the input on the left side. Useful for an `icon` or `button-icon`.
* `right`: Slot within the input on the right side. Useful for an `icon` or `button-icon`.
```javascript
import { inputStyles } from '@brightspace-ui/core/components/inputs/input-styles.js';

class MyElem extends LitElement {

static get styles() {
return inputStyles;
}

render() {
return html`<input type="text" class="d2l-input">`;
}

}
```

## Textarea Input [d2l-input-textarea]

The `<d2l-input-textarea>` is a wrapper around the native `<textarea>` element that provides auto-grow and validation behaviours. It's intended for inputting unformatted multi-line text.

<!-- docs: start hidden content -->
![example screenshot of text input](../screenshots/textarea.gif?raw=true)
<!-- docs: end hidden content -->

<!-- docs: demo live name:d2l-input-textarea -->
```html
<script type="module">
import '@brightspace-ui/core/components/inputs/input-textarea.js';
</script>
<script>
window.addEventListener('load', function () {
var input = document.querySelector('#textarea');
input.addEventListener('change', (e) => {
console.log('input-textarea change: ', input.value);
});
input.addEventListener('input', (e) => {
console.log('input-textarea input: ', input.value);
});
});
</script>
<style>
d2l-input-textarea {
width: 100%;
}
</style>
<d2l-input-textarea id="textarea" label="Description"></d2l-input-textarea>
```

<!-- docs: start hidden content -->
### Properties

| Property | Type | Description |
|---|---|---|
| `aria-invalid` | String | Indicates that the `textarea` value is invalid |
| `description` | String | A description to be added to the `textarea` for accessibility |
| `disabled` | Boolean | Disables the `textarea` |
| `label` | String, required | Label for the `textarea` |
| `label-hidden` | Boolean | Hides the label visually (moves it to the `textarea`'s `aria-label` attribute) |
| `max-rows` | Number, default: 11 | Maximum number of rows before scrolling. Less than 1 allows `textarea` to grow infinitely. |
| `maxlength` | Number | Imposes an upper character limit |
| `minlength` | Number | Imposes a lower character limit |
| `no-border` | Boolean | Hides the border |
| `no-padding` | Boolean | Removes left/right padding |
| `placeholder` | String | Placeholder text |
| `required` | Boolean | Indicates that a value is required |
| `rows` | Number, default: 5 | Minimum number of rows. If `rows` and `max-rows` are equal then auto-grow will be disabled. |
| `value` | String, default: `''` | Value of the `textarea` |

### Events

The `d2l-input-textarea` dispatches the `change` event when an alteration to the value is committed (typically after focus is lost) by the user. To be notified immediately of changes made by the user, use the `input` event.

```javascript
// fired when value changes are committed
input.addEventListener('change', (e) => {
console.log(input.value);
// dispatched when value changes are committed
textarea.addEventListener('change', (e) => {
console.log(textarea.value);
});

// fired whenever value changes occur
input.addEventListener('input', (e) => {
console.log(input.value);
// dispatched whenever value changes occur
textarea.addEventListener('input', (e) => {
console.log(textarea.value);
});
```
<!-- docs: end hidden content -->

## Applying styles to native input
### Accessibility Properties

As an alternative to using the `<d2l-input-text>` custom element, you can style a native text input inside your own element. Import `input-styles.js` and apply the `d2l-input` CSS class to the input:
To make your usage of `d2l-input-textarea` accessible, use the following properties when applicable:

| Attribute | Description |
|---|---|
| `aria-invalid` | [Indicate that the `textarea` value is invalid](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-invalid) |
| `description` | Use when label on `textarea` does not provide enough context. |
| `label` | **REQUIRED** [Acts as a primary label on the `textarea`](https://www.w3.org/WAI/tutorials/forms/labels/). Visible unless `label-hidden` is also used. |
| `label-hidden` | Use if label should be visually hidden but available for screen reader users |

### Usage

**Methods:**

| Method | Returns | Description |
|---|---|---|
| `focus()` | | Places focus in the `textarea` |
| `select()` | | Selects the contents of the `textarea` |

## Applying styles to native textarea

Native `<textarea>` elements can be styled by importing `input-styles.js` into your LitElement and applying the `d2l-input` CSS class.

<!-- docs: start hidden content -->
![example screenshot of textarea inputs](../screenshots/textarea-styles.gif?raw=true)
<!-- docs: end hidden content -->

```javascript
import { inputStyles } from '@brightspace-ui/core/components/inputs/input-styles.js';

class MyElem extends LitElement {

static get styles() {
return inputStyles;
}

render() {
return html`<input type="text" class="d2l-input">`;
return html`
<textarea class="d2l-input">
</textarea>
`;
}

}
```
89 changes: 0 additions & 89 deletions components/inputs/docs/input-textarea.md
View file

This file was deleted.

Loading

0 comments on commit 16146b7

Please sign in to comment.