omarreiss
commented
8 years ago Discussion from previous repo:
@omarreiss:
When it comes to accessibility, the following requirements apply:
- The wizard should be keyboard accessible.
- step titles should be
h1headers.- All labels should be clickable and linked to their corresponding input fields.
- All inputs should be focusable.
To be considered:
- We might want to use
A11ySpeakto communicate the navigational flow to screen readers.
When we...
- ...append a loader to the button that was clicked.
- We could tell the screenreader we are saving the current step and loading the next one.
- ...remove the loader and render the next (or previous) step after successfully saving.
- We should tell the screenreader the next step is loaded.
- ...remove the loader and trigger an alert after failing to save.
- The screenreader should pick up the alert and we don't need to do anything else. It goes without saying that we need to make sure the text of the alert is descriptive enough.
@afercia please advise.
@afercia:
@omarreiss: first things that come into my mind:
- React: I know very few about React. Learned a few things and read some documentation while working on the KB search. My concern is about the continuous re-rendering of components. As far as I know, each time
setState()is called, the component gets re-rendered with a few exceptions (e.g whensetState()is used within some React specific functions). Re-rendering a component basically means removing from the DOM a chunk (often a big chunk) of HTML and then re-injecting it with a potential, very likely, focus loss. Especially with some browsers, a focus loss implies a loss of context, forcing users to start tabbing again from the document root, where focus fallbacks. Wondering if this would need some way to manage the focus e.g. when pressing "Next" or "Previous" where the focus is supposed to land?- group of radio buttons: please consider they should always be grouped in a fieldset with a legend, as well as other form elements that may be logically grouped. This is always true for radio buttons since they're grouped by their nature. To evaluate case by case for other form elements.
- in the instantiation example. I see the "separator choices". Some of the symbols there would need a textual alternative since some of them are not announced correctly by screen readers. We've seen this this in the current separator setting in Yoast SEO. Wondering if it is worth considering an abstract, generic method to have textual alternatives.
- implementation detail: would this wizard be in a form of "in page content" or displayed in some sort of modal dialog? In the second case it would need additional stuff to make the modal dialog accessible.
@omarreiss:
@afercia
- Risk of focus loss: I think it should be possible to save the focus in the state and retain it at all times. We should keep this in mind while building.
- Radio buttons: Thanks for the context!
- Separator choices: Good point! I will change the spec a little bit to allow for further clarification per radio button. The generic method should be built into Yoast SEO.
- We want the wizard to be rendered on its own page as a standalone module to minimize risk of conflicting JS running on the same page.
@omarreiss:
@afercia Every choice can now also have a screenreaderText. Groundwork for the separator choice looks like this:
"choices": { "dash": { "label": "‐", "screenReaderText": "Dash" }, "ndash": { "label": "–", "screenReaderText": "En dash" }, "mdash": { "label": "—", "screenReaderText": "Em dash" }, "middot": { "label": "·", "screenReaderText": "Middle dot" }, "bull": { "label": "•", "screenReaderText": "Bullet" }, "asterisk": { "label": "*", "screenReaderText": "Asterisk" }, "lowast": { "label": "⁎", "screenReaderText": "Low asterisk" }, "pipe": { "label": "|", "screenReaderText": "Vertical bar" }, "tilde": { "label": "~", "screenReaderText": "Small tilde" }, "laquo": { "label": "«", "screenReaderText": "Left angle quotation mark" }, "raquo": { "label": "»", "screenReaderText": "Right angle quotation mark" }, "lt": { "label": "<", "screenReaderText": "Less than sign" }, "gt": { "label": ">", "screenReaderText": "Greater than sign" } }
The onboarding wizard is a generic library that can be used to dynamically generate an installation wizard. The wizard and all of its underlying components should be built with React in ES2015, using Babel to transpile the code to ES5. For consistency we will use browserify to manage JS modules.
Wizardcan have one or more steps.Wizardhas a "previous" and "continue" button to allow users to traverse through the steps.Stephas the following attributes:id, string, identifiertitle, string, the title of the step.fields, array, list of strings referencing fields by key.fieldhas the following attributes:component, string, references the component that should be used to render the field in the component tree.properties, object, contains all the metadata needed to render the component and configure its behavior.data, mixed, the value of the field.HTMLHTMLcomponent takes a piece of HTML and renders it. This can be useful on the opening and closing screen of the wizard, to add some introduction text, a success message or CTA towards the end.html: The html to be rendered.ChoiceChoicecomponent renders a choice interface, like a group of radio buttons or a select button. Initially it should render a group of radio buttons. We might add other representations later on.label: The label for the input element to be rendered.choices: a JSON string with choices where the key represents thevalueand the value is an object withchoiceproperties:label, string, The label of the choice.screenReaderText, string, (optional) extra context for people using screenreaders.InputInputcomponent renders a text input interface, like a regular input field or a textarea. Initially it should render a normal text input. We might add other representations later on.label: The label for the input element to be rendered.placeholder: placeholder text.pattern: a regular expression that can be used to validate the string format. (not MVP)Wizard. In the Yoast SEO example below you will find fields referencing custom component modules. They should be implemented in Yoast SEO itself, required and injected when instantiating the Wizard.Wizardis instantiated with the following propertiesfields, array, fields to be included in the steps.steps, array, steps referencing which fields belong to them.endpoint, string, used to save the data which is submitted by the user.customComponents, array, used for rendering custom components.jsonprequest with all of the data to the endpoint that was provided.Wizardin Yoast SEO would look like. Variables that should be set in Yoast SEO are wrapped in curly brackets. Custom components will be specced in future issues.