From 28ca1c39302369d4aed3a50c08b695ee7f5182c6 Mon Sep 17 00:00:00 2001 From: gossi Date: Fri, 8 Apr 2022 18:41:52 +0200 Subject: [PATCH] ui patterns showcase --- ember-handbook/app/application/template.hbs | 10 ++ .../app/component-architecture/styles.css | 8 -- .../app/components/article/component.ts | 2 +- ember-handbook/app/router.js | 14 ++ .../app/ui-patterns/faqs/template.md | 20 +++ .../checkboxes/anti-patterns/template.md | 36 +++++ .../checkboxes/index/template.md | 111 ++++++++++++++++ .../checkboxes/styling/template.md | 11 ++ .../considering-forms/template.md | 35 +++++ .../use-of-aria-live/template.md | 33 +++++ .../app/ui-patterns/index/template.md | 36 +++++ ember-handbook/app/ui-patterns/styles.css | 4 + ember-handbook/app/ui-patterns/template.hbs | 124 ++++++++++++++++++ 13 files changed, 435 insertions(+), 9 deletions(-) create mode 100644 ember-handbook/app/ui-patterns/faqs/template.md create mode 100644 ember-handbook/app/ui-patterns/form-components/checkboxes/anti-patterns/template.md create mode 100644 ember-handbook/app/ui-patterns/form-components/checkboxes/index/template.md create mode 100644 ember-handbook/app/ui-patterns/form-components/checkboxes/styling/template.md create mode 100644 ember-handbook/app/ui-patterns/general-considerations/considering-forms/template.md create mode 100644 ember-handbook/app/ui-patterns/general-considerations/use-of-aria-live/template.md create mode 100644 ember-handbook/app/ui-patterns/index/template.md create mode 100644 ember-handbook/app/ui-patterns/styles.css create mode 100644 ember-handbook/app/ui-patterns/template.hbs diff --git a/ember-handbook/app/application/template.hbs b/ember-handbook/app/application/template.hbs index ce5441a..9543ef1 100644 --- a/ember-handbook/app/application/template.hbs +++ b/ember-handbook/app/application/template.hbs @@ -20,6 +20,16 @@ Component Architecture {{/let}} + + {{#let (link "ui-patterns") as |link|}} + + UI Patterns + + {{/let}} diff --git a/ember-handbook/app/component-architecture/styles.css b/ember-handbook/app/component-architecture/styles.css index e28bf10..81486fd 100644 --- a/ember-handbook/app/component-architecture/styles.css +++ b/ember-handbook/app/component-architecture/styles.css @@ -1,11 +1,3 @@ -.page { - display: flex; - - & > main { - width: 35rem; - } -} - .spacer { display: block; height: var(--s-1); diff --git a/ember-handbook/app/components/article/component.ts b/ember-handbook/app/components/article/component.ts index 09e3a03..a624360 100644 --- a/ember-handbook/app/components/article/component.ts +++ b/ember-handbook/app/components/article/component.ts @@ -32,7 +32,7 @@ export default class ArticleLayoutBasicComponent extends Component< } get slug(): string { - return slugify(this.title, { lower: true }); + return this.title ? slugify(this.title, { lower: true }) : ''; } get toc(): object { diff --git a/ember-handbook/app/router.js b/ember-handbook/app/router.js index b2b8d48..f9c35d2 100644 --- a/ember-handbook/app/router.js +++ b/ember-handbook/app/router.js @@ -40,6 +40,20 @@ Router.map(function () { this.route('best-practices'); this.route('literature'); }); + + this.route('ui-patterns', function () { + this.route('general-considerations', function () { + this.route('considering-forms'); + this.route('use-of-aria-live'); + }); + this.route('form-components', function () { + this.route('checkboxes', function () { + this.route('anti-patterns'); + this.route('styling'); + }); + }); + this.route('faqs'); + }) }); export default Router; diff --git a/ember-handbook/app/ui-patterns/faqs/template.md b/ember-handbook/app/ui-patterns/faqs/template.md new file mode 100644 index 0000000..2ddd83f --- /dev/null +++ b/ember-handbook/app/ui-patterns/faqs/template.md @@ -0,0 +1,20 @@ +--- +description: >- + As this project identifies FAQs, they will be posted here. If you have a + question that is not answered here, please ask in the #topic-a11y channel in + the Ember Community Discord chat. +--- + +# FAQs + +## Why don't you make this into an addon? + +This is not an addon because each app will have different needs and requirements. Instead, this guide is intended to demonstrate best practices so teams can build the components that are right for their project. Additionally, an addon requires maintenance, which is a non-negligible set of work on its own. + +## Why isn't \(insert component name here\) in this guide? + +It's likely that your favorite component pattern isn't here yet because it hasn't been added yet. Or it's a carousel and those will never be here because they should never be used. + +## You made a mistake! How do I tell you about it? + +Thanks for catching it! Please file an issue here: [https://github.com/MelSumner/ember-component-patterns/issues](https://github.com/MelSumner/ember-component-patterns/issues). diff --git a/ember-handbook/app/ui-patterns/form-components/checkboxes/anti-patterns/template.md b/ember-handbook/app/ui-patterns/form-components/checkboxes/anti-patterns/template.md new file mode 100644 index 0000000..f54fc56 --- /dev/null +++ b/ember-handbook/app/ui-patterns/form-components/checkboxes/anti-patterns/template.md @@ -0,0 +1,36 @@ +--- +description: >- + Anti-patterns produce outcomes that are ineffective because they are not + complete solutions, and as such are counterproductive. Developers are advised + to be aware of anti-patterns and avoid their use. +--- + +# Anti-patterns: Checkboxes + +## Anti-pattern \#1: heading as checkbox group label + +The use of the header element with a wrapper div around a group of checkboxes may be a tempting approach at first sight. + +Consider this: + +```markup +
+

What are your preferred job titles?

+
+ + +
+
+ + +
+
+ + +
+
+``` + +At first glance, all might seem fine. However, as assistive technology such as a screen reader will not associate the title and the options correctly, this approach should be considered an anti-pattern and should be avoided. + +Instead, use the `
` with a `` to successfully contain and associate the checkbox group. It should be remembered that the default styling for these elements can be overridden and should not be considered a blocker for their use. diff --git a/ember-handbook/app/ui-patterns/form-components/checkboxes/index/template.md b/ember-handbook/app/ui-patterns/form-components/checkboxes/index/template.md new file mode 100644 index 0000000..78e4800 --- /dev/null +++ b/ember-handbook/app/ui-patterns/form-components/checkboxes/index/template.md @@ -0,0 +1,111 @@ +# Checkboxes + +## Introduction + +Checkboxes are a useful input element when it is desirable to allow users to select more than one option from a short list of options. Checkboxes can have three states: checked, not checked, and indeterminate. + +### User Expectations + +Users expect the following to be true: + +* it should be possible to navigate via keyboard +* animations should not be linked to functionality; if the user has disabled animations via system preferences, the checkbox should still be usable +* there should be a clear indicator of focus +* clicking on the label for the checkbox should also activate the checkbox itself \(this is done through properly [associating the label](../../general-considerations/considering-forms.md#labels) with the checkbox\) + +## Part One: Considering Markup + +Sometimes, a single checkbox is desirable. In these cases, a checkbox input only requires an associated label for the input: + +```markup +
+ + +
+``` + +If the user should be able to select more than one option, a checkbox group should be used. To ensure that all of the checkboxes are associated with the single group, the `name` attribute value should be the same, and the checkbox group should be wrapped with the `
` element: + +```markup +
+ What kind of jobs are you interested in (select all that apply)? +
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+``` + +### Keyboard Support + +| Key | Function | +| :--- | :--- | + + + + + + + + + +
TAB + +
    +
  • Moves keyboard focus among the checkboxes
    • +
+
+ + + + + + + + + +
SPACE + +
    +
  • Cycles the tri-state checkbox among unchecked, mixed, and checked states.
    • +
  • When the tri-state checkbox is unchecked, all the controlled checkboxes + are unchecked.
    • +
  • When the tri-state checkbox is mixed, the controlled checkboxes return + to the last combination of states they had when the tri-state checkbox + was last mixed or to the default combination of states they had when the + page loaded.
    • +
  • When the tri-state checkbox is checked, all the controlled checkboxes + are checked.
    • +
+
+ +Ember has a checkbox input helper- [https://guides.emberjs.com/release/templates/input-helpers/\#toc\_checkboxes](https://guides.emberjs.com/release/templates/input-helpers/#toc_checkboxes) - but it should not be used in the place of common sense. Use this helper if it is sensible to do so. + +\(More explicit guidance and additional scenarios coming soon\) + +## Part Three: Abstracting for reuse + +Coming soon! + +## References + +* [https://www.w3.org/TR/wai-aria-practices-1.1/\#checkbox](https://www.w3.org/TR/wai-aria-practices-1.1/#checkbox) +* [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox) +* [https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox\_role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/checkbox_role) +* [https://codepen.io/jensimmons/pen/KKPzxJa](https://codepen.io/jensimmons/pen/KKPzxJa) + + +Feedback is welcome! Visit the [GitHub repository for this project](https://github.com/MelSumner/ember-component-patterns) to raise an issue. + diff --git a/ember-handbook/app/ui-patterns/form-components/checkboxes/styling/template.md b/ember-handbook/app/ui-patterns/form-components/checkboxes/styling/template.md new file mode 100644 index 0000000..1cb953a --- /dev/null +++ b/ember-handbook/app/ui-patterns/form-components/checkboxes/styling/template.md @@ -0,0 +1,11 @@ +# Styling: Checkboxes + +## Preventing Text Selection + +Occasionally, when a checkbox is activated or deactivated, the input's label text appears selected. If this is bothersome, a little CSS can help: + +```css +label { + user-select: none; +} +``` diff --git a/ember-handbook/app/ui-patterns/general-considerations/considering-forms/template.md b/ember-handbook/app/ui-patterns/general-considerations/considering-forms/template.md new file mode 100644 index 0000000..60d982b --- /dev/null +++ b/ember-handbook/app/ui-patterns/general-considerations/considering-forms/template.md @@ -0,0 +1,35 @@ +--- +description: >- + This page contains some general knowledge that may be helpful to review before + looking at the form component guides. +--- + +# Considering Forms + +## Labels + +All form inputs are required to have an associated `