Readme updates (dojo#546)

README.md

@@ -7,9 +7,6 @@
 A suite of pre-built Dojo 2 widgets, ready to use in your web application.
 These widgets are built using Dojo 2's widget authoring system [(@dojo/widget-core)](https://github.com/dojo/widget-core).
 
-**WARNING** This is _beta_ software. While we do not anticipate significant changes to the API at this stage, we may feel the need to do so.
-This is not yet production ready, so you should use at your own risk.
-
 - [Usage](#usage)
 - [Features](#features)
 - [Conventions](#conventions)
@@ -51,7 +48,7 @@ This allows our [`dojo cli`](https://github.com/dojo/cli) build tooling to make
 
 - All widgets are supported in all evergreen browsers (Chrome, Edge, Firefox, IE11+, and Safari) as well as popular mobile browsers (Mobile Safari, Chrome on Android).
 
-- All widgets support accessibility (`a11y`) out of the box.
+- All widgets are designed to be accessible. If custom ARIA semantics are required, widgets have an `aria` property that may be passed an object with custom `aria-*` attributes.
 
 - All widgets are fully themeable. Example themes are available in the [@dojo/themes](https://github.com/dojo/themes) repository.
 
@@ -102,14 +99,16 @@ Live examples of current widgets are available in the [widget showcase](https://
 ### Misc widgets
 [Dialog](src/dialog/README.md)
 
+[GlobalEvent](src/global-event/README.md)
+
+[Icon](src/icon/README.md)
+
 [Progress](src/progress/README.md)
 
 [Toolbar](src/toolbar/README.md)
 
 [Tooltip](src/tooltip/README.md)
 
-[GlobalEvent](src/global-event/README.md)
-
 ## Conventions
 
 ### EventHandlers
@@ -119,9 +118,9 @@ The naming convention for event handlers is as follows:
 
 - if the parent of the widget has the power to decide *if* an event is successful, i.e. can cancel the event, then the child widget will call an event handler in the following format:
 
-`onRequest[X]`, e.g. for a `close` event, the event handler called by the child widget must be called `onRequestClose`
+ `onRequest[X]`, e.g. for a `close` event, the event handler called by the child widget must be called `onRequestClose`
 
-Here the child widget is requesting that the `close` event take place.
+ Here the child widget is requesting that the `close` event take place.
 
 - for events that will occur regardless of child/parent interaction, then the `Request` naming convention is dropped:
 
@@ -133,6 +132,8 @@ Here the child widget is requesting that the `close` event take place.
 We use [font awesome](http://fontawesome.io/) for icons.
 Where a theme requires specific icons that are not part of the Font Awesome set, then those themes will ship their own icons.
 
+There is an [icon widget](src/icon/README.md) that aids in creating in proper semantics and provides type-checking for the type of icon.
+
 ### Coding conventions
 
 `px vs. em` - we specify font sizes in `px`.
@@ -169,7 +170,12 @@ export class MyWidget extends Button {
 }
 ```
 
-Dojo 2 widgets provide standard extension points to allow you to customize their behavior. For more details, please refer to the [widget authoring system](https://github.com/dojo/widget-core).
+Dojo 2 widgets provide standard extension points to allow you to customize their behavior. For more details, please refer to the [widget authoring system](https://github.com/dojo/widget-core#decorator-lifecycle-hooks).
+
+Individual widgets also provide certain types of extension points where applicable:
+- `render*`: Large render functions are split up into multiple smaller pieces that can be more easily overridden to create custom vdom.
+- `getModifierClasses`: Modify the array of conditionally applied classes like `css.selected` or `css.disabled`.
+Not all widgets include these extension points, and some have additional overridable methods.
 
 
 ## How do I contribute?

src/accordion-pane/README.md

@@ -1,6 +1,6 @@
 # @dojo/widgets/accordion-pane widget
 
-Dojo 2's `AccordionPane` component can be used to show multiple pieces of content inside collapsible panes within a common parent component. It provides responsive styling and a mechanism of control over multiple child `TitlePane` components.
+Dojo 2's `AccordionPane` component can be used to show multiple pieces of content inside collapsible panes within a common parent component. It provides a mechanism of control over multiple child `TitlePane` components.
 
 ## Features
 

src/button/README.md

@@ -62,3 +62,4 @@ The following CSS classes are available on the root node of the `Button` widget
 - `disabled`: Applied if `properties.disabled` is true
 - `popup`: Applied if `properties.popup` has a non-false value
 - `pressed`: Applied if `properties.pressed` is true
+- `addon`: Applied to the popup icon container if `properties.popup` has a non-false value

src/calendar/README.md

@@ -5,11 +5,11 @@ Dojo 2's `Calendar` renders a date grid with a dropdown month and year picker. T
 
 - Renders a date grid with weekday headers, defaulting to the current month
 
-![Image of basic calendar](http://placekitten.com/450/300)
+![Image of basic calendar](../../.github/calendar-dategrid.png)
 
 - Clicking on the current month label opens a month picker that allows you to infinitely cycle through years and choose a month
 
-![Image of open month picker](http://placekitten.com/450/300)
+![Image of open month picker](../../.github/calendar-months.png)
 
 ### Keyboard Usage
 - All controls are in the tab order and accessible by keyboard

src/checkbox/README.md

@@ -15,6 +15,8 @@ Dojo 2's `Checkbox` widget provides either a wrapped, styleable checkbox widget
 
 When using the toggle mode, only one of `onLabel` and `offLabel` will be read, based on the current state. E.g. if checked with a label of "Sample Checkbox", the full screen reader-accessible label would read "Sample Checkbox On".
 
+If the `label` property is not used, we recommend creating a separate `label` and pointing it at the input's `widgetId` property.
+
 ## Example Usage
 
 ```typescript

src/combobox/README.md

@@ -5,10 +5,7 @@ Dojo 2's `ComboBox` widget provides a form control that allows users to either e
 ## Features
 
 - Compatible with any underlying data provider, data format, or store
-- Custom components can be used for the list of results and each individual result
-- Completely keyboard accessible
-
-![Image of basic combobox](http://placekitten.com/450/300)
+- Keyboard accessible
 
 ### Keyboard Usage
 
@@ -33,9 +30,7 @@ Dojo 2's `ComboBox` widget provides a form control that allows users to either e
 
 ### Accessibility Features
 
-Beyond complete keyboard accessibility, `ComboBox` ensures that all appropriate ARIA attributes are included. To guarantee an excellent experience for all users, however, the following should be included with every `ComboBox`:
-
-- `inputProperties.describedBy`: the ID of an element that provides descriptive text for the input value's expected format. For example, if the input value should be the name of a US state, an element with the same ID as `inputProperties.describedBy` might be, "Accepts any valid US state name.".
+Beyond complete keyboard accessibility, `ComboBox` ensures that all appropriate ARIA attributes are included. All instances of this widget should make use of the `label` property or a separate `label` node associated with the combobox's `widgetId` property.
 
 ### Internationalization Features
 
@@ -119,29 +114,15 @@ w(ComboBox, {
 });
 ```
 
-*Custom Result Component*
+*Custom formatted option*
 ```typescript
 import ComboBox from '@dojo/widgets/combobox';
-// The component used by default to render a result item
-import ResultItem from '@dojo/widgets/combobox/ResultItem';
-import { w } from '@dojo/widget-core/d';
-
-// Extend default ResultItem component to show an icon next to each label
-class CustomResultItem extends ResultItem {
-	// We only need to override one method. Normally this method just returns
-	// the result; In this case, let's return an <img> and the result
-	renderResult(result: any) {
-		return v('div', [
-			v('img', { src: 'icon.png' }),
-			result
-		]);
-	}
-}
+import { v, w } from '@dojo/widget-core/d';
 
 w(ComboBox, {
+	getResultLabel: (result: string) => v('span', { style: 'color: blue' }, [ result ]),
 	results: ['foo', 'bar', 'baz'],
 	value: this.state.currentValue,,
-	CustomResultItem: CustomResultItem,
 	onChange: (value: string) => this.setState({ currentValue: value })
 });
 ```

src/dialog/README.md

@@ -1,15 +1,13 @@
 # @dojo/widgets/dialog widget
 
-Dojo 2's `Dialog` component can be used to show content inside a window over top the application content. It provides default styling for a titlebar, content area, underlay, and a close button, and will respond to different screen sizes responsively.
+Dojo 2's `Dialog` component can be used to show content inside a window over top the application content. It provides default styling for a titlebar, content area, underlay, and a close button.
 
 ## Features
 
 - Can be used as a modal window or classic dialog
 - Possible to show a semi-transparent underlay
 - Custom CSS animations can be provided
 
-![Image of basic dialog](http://placekitten.com/450/300)
-
 ### Accessibility Features
 
 - The titlebar and content have screen-reader-accessible labels and instructions

src/label/README.md

@@ -1,7 +1,9 @@
 # @dojo/widgets/label widget
 
-Dojo 2's `Label` widget creates a `<label>` element that wraps its children and inserts a text node as either the first or last child.
-
+Dojo 2's `Label` widget creates a `<label>` element that wraps its children and inserts a text node as either the first or last child. It is included by default in all form input widgets, including `ComboBox` and `TimePicker`. Input widgets control the text, visibility, and placement of the label through the following properties:
+- `label`: String used as label text
+- `labelAfter`: If true, the label node follows the input node in the generated vdom
+- `labelHidden`: This corresponds to the `hidden` class on the Label widget.
 
 ## Features
 
@@ -18,30 +20,27 @@ Dojo 2's `Label` widget creates a `<label>` element that wraps its children and
 ## Example Usage
 
 ```typescript
-// Basic usage, creates a label before the input
-w(Label, {
-	label: 'Your Name'
-}, [
+// Basic usage of a label wrapping an input
+w(Label, [
+	'Name'
 	v('input', { type: 'text' })
 ]);
 
-// Label after the input
-w(Label, {
-	label: {
-		content: 'Email',
-		before: false
-	}
-}, [
-	v('input', { type: 'email' })
+// Label associated with input by id
+v('div', [
+	w(Label, {
+		forId: 'emailId'
+	}, [ 'Email' ]),
+	v('input', {
+		id: 'emailId',
+		type: 'email'
+	})
 ]);
 
 // Hidden label
 w(Label, {
-	label: {
-		content: 'Favorite color',
-		hidden: true
-	}
+	hidden: true
 }, [
-	v('input', { type: 'color' })
+	'Visually hidden label text'
 ]);
 ```

src/listbox/README.md

@@ -0,0 +1,117 @@
+# @dojo/widgets/listbox widget
+
+Dojo 2's `Listbox` provides a base widget that can be used as an options menu within a `Select` or `ComboBox` component, or as a standalone multi-select component
+
+## Features
+
+- Compatible with any underlying data provider, data format, or store
+- Allows customization of option state and vdom through reactive patterns
+- Handles all keyboard interactions if given focus
+- Can be controlled through `activeIndex` and `visualFocus`, e.g. in a `ComboBox` where focus stays on the text input
+
+### Keyboard Usage
+
+`Listbox` supports keyboard navigation for highlighting and selecting options
+
+- Enter Key: selects the current option and closes the menu
+- Space Key: selects the current option and closes the menu
+- Up Arrow: highlights the previous option
+- Down Arrow: highlights the next option
+- Home/Page Up: highlights the first option
+- End/Page Down: highlights the last option
+
+### Accessibility Features
+
+Since `Listbox` is primarily intended for use as a base for other components like `Select` and `ComboBox`, it does not have a `label` property. When used as a standalone component, a separate `label` node should be created and associated with the listbox's `widgetId` property.
+
+### Internationalization Features
+
+Option text is handled through the `getOptionLabel` property. Localization is handled by the parent component and localized strings can be reactively passed in using this method.
+
+## Example Usage
+
+*Basic Listbox*
+```typescript
+import Listbox from '@dojo/widgets/listbox';
+import { w } from '@dojo/widget-core/d';
+
+interface OptionData {
+	disabled: boolean;
+	label: string;
+	value: string;
+};
+
+let listboxIndex = 0;
+let optionData: CustomOption[];
+let value: string;
+
+v('label', {
+	for: 'listbox1'
+}, [ 'Simple listbox example' ]),
+w(Listbox, {
+	key: 'listbox1',
+	activeIndex: listboxIndex,
+	widgetId: 'listbox1',
+	optionData,
+	getOptionLabel: (option: CustomOption) => option.value,
+	getOptionDisabled: (option: CustomOption) => !!option.disabled,
+	getOptionSelected: (option: CustomOption) => option.value === value,
+	onActiveIndexChange: (index: number) => {
+		listboxIndex = index;
+		this.invalidate();
+	},
+	onOptionSelect: (option: any, index: number) => {
+		value = option.value;
+		this.invalidate();
+	}
+});
+```
+
+*Multi-select Listbox*
+```typescript
+import Listbox from '@dojo/widgets/listbox';
+import { w } from '@dojo/widget-core/d';
+
+interface OptionData {
+	disabled: boolean;
+	label: string;
+	selected: boolean;
+	value: string;
+};
+
+let listboxIndex = 0;
+let optionData: CustomOption[];
+
+v('label', {
+	for: 'listbox2'
+}, [ 'Select multiple options' ]),
+w(Listbox, {
+	key: 'listbox2',
+	activeIndex: listboxIndex,
+	widgetId: 'listbox2',
+	optionData,
+	getOptionLabel: (option: CustomOption) => option.value,
+	getOptionDisabled: (option: CustomOption) => !!option.disabled,
+	getOptionSelected: (option: CustomOption) => !!option.selected,
+	onActiveIndexChange: (index: number) => {
+		listboxIndex = index;
+		this.invalidate();
+	},
+	onOptionSelect: (option: any, index: number) => {
+		optionData[index].selected = !optionData[index].selected;
+		optionData = [ ...optionData ];
+		this.invalidate();
+	}
+});
+```
+
+## Theming
+
+The following CSS classes are used to style the `Listbox` widget and should be provided by custom themes:
+
+- `focused`: Applied to both the root node if the component is focused or contains focus
+- `option`: Applied to the option nodes
+- `activeOption`: Applied to the currently highlighted option
+- `disabledOption`: Applied to any disabled options
+- `selectedOption`: Applied to any selected options
+- `root`: Applied to both the root node

src/listbox/index.ts

@@ -138,9 +138,11 @@ export class ListboxBase<P extends ListboxProperties = ListboxProperties> extend
 				onActiveIndexChange && onActiveIndexChange(newIndex, key);
 				break;
 			case Keys.Home:
+			case Keys.PageUp:
 				onActiveIndexChange && onActiveIndexChange(0, key);
 				break;
 			case Keys.End:
+			case Keys.PageDown:
 				onActiveIndexChange && onActiveIndexChange(optionData.length - 1, key);
 				break;
 		}

src/radio/README.md

@@ -1,6 +1,6 @@
 # @dojo/widgets/radio widget
 
-Dojo 2's `Radio` widget provides either a styleable radio widget, optionally wrapped in a label.
+Dojo 2's `Radio` widget provides a styleable radio widget with an optional label.
 
 
 ## Features
@@ -12,6 +12,8 @@ Dojo 2's `Radio` widget provides either a styleable radio widget, optionally wra
 
 `Radio` ensures that the proper attributes (ARIA or otherwise) are set along with classes when properties such as `disabled`, `readOnly`, `invalid`, etc. are used.
 
+If the `label` property is not used, we recommend creating a separate `label` and pointing it at the input's `widgetId` property.
+
 ## Example Usage
 
 ```typescript