Cleanup widget readme files (dojo#942)

* Cleanup accordion pane readme

* button and calendar

* Updated card to remove circular desc. Based on material

* cleanup checkbox wording

* cleanup checkbox group

* cleaned up chip wording to align w/ material

* cleaned up wording constrained-input

* small text cleanup

* removed example from global-event

* standardized description, minor wording

* removed label property descriptions; cleanup

* menu cleanup

* number-input cleanup

* outlined button cleanup

* popup cleanup

* minor cleanup

* minor edits

* minor cleanup

src/accordion-pane/README.md

@@ -8,8 +8,5 @@ Dojo's `AccordionPane` component can be used to show multiple pieces of content
 
 ### Accessibility Features
 
-An `AccordionPane` expects all children to be `TitlePane` components, and as such, supports standard keyboard navigation for toggling child content open or closed.
-
-**TitleBar Events**:
-
-- Space bar: toggles the pane content of a closeable child `TitlePane`
+- Supports standard tab navigation
+- Space bar toggles the pane content of a closeable child `TitlePane`

src/button/README.md

@@ -1,16 +1,13 @@
 # @dojo/widgets/button
 
-Dojo's `Button` widget creates a `<button>` element
-
+Dojo's `Button` widget creates a `<button>` element with support `pressed` and `disabled` states.
 
 ## Features
 
 - Provides an API for valid `<button>` attributes
 - Can be used to create a toggle button (i.e. a button with an on/off state)
-- Provides an easy API to create a button controlling a popup
 
 ### Accessibility Features
 
 - The basic button provides a strongly typed `type` property, as well as `disabled`
 - Setting `pressed` to create a toggle button handles `aria-pressed`
-- Creating a popup button with `popup` sets `aria-haspopup`, `aria-controls`, and `aria-expanded`

src/calendar/README.md

@@ -1,20 +1,21 @@
 # @dojo/widgets/calendar
-Dojo's `Calendar` renders a date grid with a dropdown month and year picker. The displayed month and year are controlled via properties, defaulting to the current day. Given the limitations of scaling date grid while maintaining usability, the calendar is not fully responsive at small screen sizes; it is instead recommended to switch to an alternative date picker for mobile.
+Dojo's `Calendar` renders a date grid with a dropdown month and year picker. The displayed month and year are controlled via properties, defaulting to the current day. Given the limitations of scaling the date grid while maintaining usability, the calendar is not fully responsive at small screen sizes; it is instead recommended to use an alternative date picker for mobile.
 
 ## Features
 
-- Renders a date grid with weekday headers, defaulting to the current month
-- Clicking on the current month label opens a month picker that allows you to infinitely cycle through years and choose a month
+- Defaults to the current month
+- Renders a date grid with weekday headers
+- Clicking on the current month or year label opens a picker that allows you to select a new value
 
 ### Keyboard Usage
 - All controls are in the tab order and accessible by keyboard
 - Arrow keys move focus in the date grid, and navigating to a disabled date updates the month
 - Page up and page down move to the first and last date in the month
-- Arrow keys change the year within the month control popup
+- Arrow keys change the selection within the month and year popup
 
 ### Accessibility Features
-- The month label is read by screen readers when updated through `aria-live: polite`
-- The month popup trigger, year control, month radios, and previous/next month arrows all have screen-reader-accessible labels and instructions
+- The `month` label is read by screen readers when updated through `aria-live: polite`
+- The month popup label, year control, month radios, and previous/next month arrows all have screen-reader-accessible labels and instructions
 - The weekdays and month radios are marked up with `<abbr>` tags that contain unabbreviated titles
 - Focus is controlled when opening and closing the month popup
 

src/card/README.md

@@ -1,8 +1,8 @@
 # @dojo/widgets/card
 
-Dojo's `Card` widget provides a simple wrapper for elements that should be designated and styled as a card component.
+Dojo's `Card` widget provides a simple container for content and actions with a similar theme.
 
 ### Features
 
-- Create a wrapper with a consistent style
-- Easily add actions to the card
+- Wrap content with a consistent style
+- Include actions with the card

src/checkbox-group/README.md

@@ -1,9 +1,9 @@
-# @dojo/widgets/checkbox-group widget
+# @dojo/widgets/checkbox-group
 
 Dojo's `CheckboxGroup` widget provides an opinionated way to use a group of check boxes in a form.
 
 ## Features
 
 - Takes an options property to define the checkboxes to create
 - Offers a custom renderer allowing the user to create their own checkboxes
-- Provides a middleware for custom use
+- Provides a checkbox group middleware when using a custom renderer

src/checkbox-group/index.tsx

@@ -16,7 +16,7 @@ interface CheckboxGroupProperties {
 	options: CheckboxOptions;
 	/** Callback for the current value */
 	onValue(value: string[]): void;
-	/** Custom renderer for the checkboxes, recieves the checkbox group middleware and options */
+	/** Custom renderer for the checkboxes, receives the checkbox group middleware and options */
 	renderer?(
 		name: string,
 		middleware: ReturnType<ReturnType<typeof checkboxGroup>['api']>,

src/checkbox/README.md

@@ -1,18 +1,17 @@
-# @dojo/widgets/checkbox widget
+# @dojo/widgets/checkbox
 
 Dojo's `Checkbox` widget provides either a wrapped, styleable checkbox widget or an on/off toggle. Both the normal and toggle `Checkbox` modes use the native `<input type="checkbox">` as a base.
 
-
 ## Features
 
-- Creates either a normal checkbox or toggle switch
+- Creates either a normal checkbox or toggle switch based on the `mode` property
 - Correctly handles a11y attributes
-- Wraps the input in a visible or invisible but accessible `<label>` if the `label` property is added
+- Wraps the input in a `<label>` if the `label` property is added
 
 ### Accessibility Features
 
 `Checkbox` ensures that the proper attributes (ARIA or otherwise) are set along with classes when properties such as `disabled`, `readOnly`, `invalid`, etc. are used.
 
-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".
+When using the toggle mode only one of `onLabel` or `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.

src/chip/README.md

@@ -1,7 +1,6 @@
-# @dojo/widgets/chip widget
-
-Dojo's `Chip` widget allows content and particularly user inputs to be displayed more clearly and enables interaction such as removing entered values or clicking them to trigger some action
+# @dojo/widgets/chip
 
+Dojo's `Chip` widget allows information and user inputs to be displayed as a single compact entity. Supported interactions include removing a chip or clicking them to trigger an action.
 
 ## Features
 

src/constrained-input/README.md

@@ -1,6 +1,6 @@
 # @dojo/widgets/constrained-input
 
-Dojo's `ConstrainedInput` component can be used to show a text input that follows certain pre-defined validation constraints. This can be used to quickly create an input that meets certain minimum standards like a username or password input.
+Dojo's `ConstrainedInput` component creates a text input that follows certain pre-defined validation constraints. This can be used to quickly create an input that meets certain minimum standards like a username or password input.
 
 ## Features
 

src/dialog/README.md

@@ -1,6 +1,6 @@
 # @dojo/widgets/dialog
 
-Dojo'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.
+Dojo's `Dialog` component shows content inside a window over top the application content. It provides default styling for a titlebar, content area, underlay, and a close button.
 
 ## Features
 

src/email-input/README.md

@@ -1,3 +1,3 @@
 # @dojo/widgets/email-input
 
-Dojo's `EmailInput` widget provides a basic email input widget.
+Dojo's `EmailInput` widget provides a basic email input widget with validation.

src/global-event/README.md

@@ -1,26 +1,8 @@
-# @dojo/widgets/global-event widget
+# @dojo/widgets/global-event
 
 Dojo's `GlobalEvent` enables events to be registered on `document` and `window` reactively.
 
 ## Features
 
 - Can be used as a wrapping widget and will return children on render or used within a widgets returned DNode structure and returns `null` from `render`.
 - Reactively adds and removes global events listeners based on the `window` and `document` properties.
-
-## Example Usage
-
-```ts
-// Wrapping DNodes as children
-w(GlobalEvent, {
-	window: { keydown: () => {} },
-	document: { focus: () => {} }
-}, [
-	// Add widget's DNodes
-]);
-
-// Used in the DNode tree
-v('div', { key: 'root' }, [
-	w(GlobalEvent, { window: { click: () => {} } }),
-	w(Button, { /* button options */ })
-]);
-```

src/grid/README.md

@@ -1,11 +1,11 @@
 # @dojo/widgets/grid
 
-A reactive lightweight, customizable grid widget built with Dojo.
+Dojo's `Grid` is a reactive lightweight, customizable grid widget.
 
 ## Features
 
  * On-demand virtual rendering with supports for large data-sets
  * Backed by [`@dojo/framework/stores`](https://github.com/dojo/framework/tree/master/src/stores)
- * Editable cells
+ * Cells may be editable or read-only
  * Filtering and Sorting by column
  * Custom cell renderers

src/icon/README.md

@@ -1,3 +1,3 @@
 # @dojo/widgets/icon
 
-Dojo's `Icon` widget renders an icon.
+Dojo's `Icon` widget renders one of Dojo's predefined font icons.

src/label/README.md

@@ -1,18 +1,13 @@
 # @dojo/widgets/label
 
-Dojo'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.
+Dojo's `Label` widget creates a `<label>` element that wraps its children. It is included by default in all form input widgets (including `ComboBox` and `TimePicker`).
 
 ## Features
 
-- Provides an API to add an accessible label before (default) or after the form control
 - The label may be visually hidden while remaining accessible to screen readers
-- `properties.label` may take an options object or a string
 - All form controls in `@dojo/widgets` make use of the label and share the same `properties.label` API
 
 ### Accessibility Features
 
 - The label is implicitly tied to its form control, so it should not be passed children with non-label text content
-- If `properties.label.hidden` is true, it uses styles that leave the text content accessible to screen readers
+- If the `hidden` property is true, it uses styles that leave the text content accessible to screen readers

src/menu/README.md

@@ -1,18 +1,18 @@
 # @dojo/widgets/menu
 
-Dojo's `Menu` provides a base widget that can be used as a menu or an options menu within a `Select`, `Typeahead` etc.
+Dojo's `Menu` provides a base widget that can be used as a menu or an options menu within a `Select`, `Typeahead`, etc.
 
 ## Features
 
 - Handles keyboard interactions if given focus
 - Can be controlled through `activeIndex` and `onActiveIndexChange` in conjunction with `focusable: false`.
 - Handles native style scrolling
 - Provides a custom renderer for more complex menu items
-- Active selection follows mouse as per native behaviour
+- Active selection follows mouse as per native behavior
 
 ### Keyboard Usage
 
-`Menu` supports keyboard navigation for highlighting and selecting options
+`Menu` supports keyboard navigation for highlighting and selecting options.
 
 - Enter Key: selects the current option
 - Space Key: selects the current option

src/menu/index.tsx

@@ -28,7 +28,7 @@ export interface MenuProperties {
 	onRequestClose?(): void;
 	/** Optional callback, when passed, the widget will no longer control it's own active index / keyboard navigation */
 	onActiveIndexChange?(index: number): void;
-	/** Optional proprty to set the activeIndex when it is being controlled externally */
+	/** Optional property to set the activeIndex when it is being controlled externally */
 	activeIndex?: number;
 	/** Determines if the widget can be focused or not. If the active index is controlled from elsewhere you may wish to stop the menu being focused and receiving keyboard events */
 	focusable?: boolean;

src/number-input/README.md

@@ -1,17 +1,18 @@
-# @dojo/widgets/input/number-input
+# @dojo/widgets/number-input
 
 Dojo's `NumberInput` widget provides a basic number input widget with an optional label.
 
-
 ## Features
 
 - Correctly handles a11y attributes
-- Associates a visible or invisible but accessible `<label>` with the input if the `label` property is added
+- Associates an accessible `<label>` with the input when the `label` property is added
 - Allows leading / trailing icons / text to be added
 
 ### Accessibility Features
 
-`NumberInput` ensures that the proper attributes (ARIA or otherwise) are set along with classes when properties such as `disabled`, `readOnly`, etc. are used. It also provides an API for custom ARIA implementations of `aria-describedby` and `aria-controls`. It also sets `aria-invalid` when validation fails.
+- Ensures that the proper attributes (ARIA or otherwise) are set along with classes when properties such as `disabled`, `readOnly`, etc. are used
+- Additional custom ARIA labels may be added with the `aria` property
+- Sets `aria-invalid` when validation fails
 
 If the `label` property is not used, we recommend creating a separate `label` and pointing it at the input's `widgetId` property.
 

src/outlined-button/README.md

@@ -1,6 +1,3 @@
-# @dojo/widgets/outlined-button widget
+# @dojo/widgets/outlined-button
 
-Dojo's `OutlinedButton` widget creates a `<button>` element
-
-The `OutlinedButton` widget wraps the `Button` widget with an additional class for alternative styling.
-For details on the features, usage, and accessibility of the `OutlinedButton`, refer to the [Button README](../button/README.md)
+Dojo's `OutlinedButton` widget creates a Dojo `Button` widget with additional classes for alternative styling.

src/popup/README.md

@@ -1,6 +1,6 @@
 # @dojo/widgets/popup
 
-The `popup` widget allows popup content to be shown relative to a trigger.
-The popup will can be positioned `above` or `below` the trigger. The popup will move the content appropriately if there is not room in the desired position.
+Dojo's `Popup` widget allows popup content to be shown relative to a trigger widget.
+The popup can be positioned `above` or `below` the trigger. The popup will move the content appropriately if there is not room in the desired position.
 
-A `body` tag is used to render the popup as well as an underlay to ensure that the page cannot be interacted with whilst the popup is visible. The popup is designed to be used with toggle buttons / selects / menus etc.
+A `body` tag is used to render the popup as well as an underlay to ensure that the page cannot be interacted with whilst the popup is visible. The popup is designed to be used with toggle buttons / selects / menus.

src/popup/index.tsx

@@ -9,11 +9,11 @@ import { createICacheMiddleware } from '@dojo/framework/core/middleware/icache';
 export type PopupPosition = 'above' | 'below';
 
 export interface PopupProperties {
-	/** Property to define if the popup wrapper should match the trigger width, defaults to true */
+	/** if the popup wrapper should match the trigger width, defaults to true */
 	matchWidth?: boolean;
-	/** Property to define where the popup should render relative to the trigger, defaults to below */
+	/** where the popup should render relative to the trigger, defaults to below */
 	position?: PopupPosition;
-	/** Property to define if the underlay should be visible, defaults to false */
+	/** if the underlay should be visible, defaults to false */
 	underlayVisible?: boolean;
 }
 

src/progress/README.md

@@ -1,7 +1,6 @@
 # @dojo/widgets/progress
 
-Dojo's `progress` widget provides a themeable progress bar with a customizable output display.
-
+Dojo's `Progress` widget provides a themeable progress bar with a customizable output display.
 
 ## Features
 

src/radio/README.md

@@ -2,11 +2,10 @@
 
 Dojo's `Radio` widget provides a styleable radio widget with an optional label.
 
-
 ## Features
 
 - Correctly handles a11y attributes
-- Wraps the input in a visible or invisible but accessible `<label>` if the `label` property is added
+- Wraps the input in an accessible `<label>` when the `label` property is added
 
 ### Accessibility Features
 

src/raised-button/README.md

@@ -1,6 +1,3 @@
-# @dojo/widgets/button widget
+# @dojo/widgets/button
 
-Dojo's `RaisedButton` widget creates a `<button>` element.
-
-The `RaisedButton` widget extends the `Button` widget, adding an additional class for styling.
-For features, usage, theming, and accessibility, please refer to the [Button README](../button/README.md)
+Dojo's `RaisedButton` widget creates a Dojo `Button` widget with additional classes for alternative styling.

src/range-slider/README.md

@@ -2,7 +2,6 @@
 
 Dojo's `RangeSlider` widget creates a range slider control with a styleable track, fill, and draggable thumb controls.
 
-
 ## Features
 
 - Horizontal slider with a track, fill, and two thumbs

src/select/README.md

@@ -5,7 +5,7 @@ Dojo's `Select` provides a dropdown menu form control using either the native `<
 ## Features
 
 - Compatible with any underlying data provider, data format, or store
-- Allows customization of option state and vdom through reactive patterns
+- Allows customization of option state and vdom
 - Keyboard accessible
 
 ### Keyboard Usage
@@ -29,7 +29,7 @@ The custom `Select` supports keyboard navigation for opening and closing the opt
 
 ### Accessibility Features
 
-The simplest way to create a an accessible select field that works across all browsers, devices, and assistive tech is to set `useNativeElement` to true. However, the custom element also sets appropriate ARIA attributes handles keyboard interactions.
+The simplest way to create an accessible select field that works across all browsers, devices, and assistive tech is to set `useNativeElement` to true. However, the custom element also sets appropriate ARIA attributes handles keyboard interactions.
 
 All instances of this widget should make use of the `label` property or a separate `label` node associated with the select's `widgetId` property.
 

src/slide-pane/README.md

@@ -2,7 +2,6 @@
 
 Dojo's `SlidePane` widget provides a component capable of moving content into or out of the viewport, as is commonly used for mobile navigation menus.
 
-
 ## Features
 
 - Can be positioned on the left or right edge of the screen

src/slider/README.md

@@ -2,7 +2,6 @@
 
 Dojo's `Slider` widget creates a range slider control with a styleable track, fill, and draggable thumb control.
 
-
 ## Features
 
 - Horizontal or vertical slider with a track, fill, and single thumb

src/tab-controller/README.md

@@ -1,6 +1,6 @@
 # @dojo/widgets/tab-controller
 
-Dojo's `TabController` widget provides a user interface capable of displaying tabbed content. The content shown at any given time is based on the currently-selected tab button.
+Dojo's `TabController` widget provides a user interface capable of displaying tabbed content. The content shown at any given time is based on the children of the currently-selected tab button.
 
 ## Features
 

src/text-area/README.md

@@ -1,13 +1,12 @@
 # @dojo/widgets/text-area
 
-Dojo's `TextArea` widget provides a wrapped native `textarea` input, optionally with a label.
-
+Dojo's `TextArea` widget provides a wrapped native `textarea` input with an optional label.
 
 ## Features
 
 - Provides an API for valid `<textarea>` attributes
 - Correctly handles a11y attributes
-- Associates a visible or invisible but accessible `<label>` with the `textarea` if the `label` property is added
+- Associates an accessible `<label>` with the `textarea` if the `label` property is added
 
 ### Accessibility Features