From 793e2dbf5046245312942a36605124b015710c81 Mon Sep 17 00:00:00 2001
From: Theodor Vararu <theo@vararu.org>
Date: Tue, 30 May 2017 15:42:57 +0100
Subject: [PATCH] Update usage section in README

- Clarify usage with and without module systems
- Clarify basic usage with a container `<div>`
---
 README.md | 49 +++++++++++++++++++++++++++++++++----------------
 1 file changed, 33 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 465f96a9..6d98eec2 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@
 
 ## Installation / usage
 
-### Using npm
+### Using npm and a module system
 
 Install it by running:
 
@@ -27,45 +27,62 @@ Install it by running:
 npm install --save accessible-autocomplete
 ```
 
-Import it using a module system like Webpack:
-
-```js
-import accessibleAutocomplete from 'accessible-autocomplete'
-```
-
-Or using a script tag:
+The `accessibleAutocomplete` function will render an autocomplete `<input>` and its accompanying suggestions and `aria-live` region. Your page should provide a `<label>` and a container element:
 
 ```html
-<script type="text/javascript" src="node_modules/accessible-autocomplete/dist/accessible-autocomplete.min.js"></script>
+<label for="my-autocomplete">Select your country</label>
+<div id="my-autocomplete-container"></div>
 ```
 
-And then call the `accessibleAutocomplete` function, providing a suggestion engine:
+Then import it using a module system like Browserify / Webpack / Rollup, and call the `accessibleAutocomplete` function, providing a suggestion function:
 
 ```js
+import accessibleAutocomplete from 'accessible-autocomplete'
+
 function suggest (query, populateResults) {
   const results = [
     'France',
     'Germany',
     'United Kingdom'
   ]
-  const filteredResults = results.filter(result => result.indexOf(query) !== -1)
+  const filteredResults = results.filter(result => result.toLowerCase().indexOf(query.toLowerCase()) !== -1)
   populateResults(filteredResults)
 }
 
 accessibleAutocomplete({
   element: document.querySelector('#my-autocomplete-container'),
-  id: 'my-autocomplete',
+  id: 'my-autocomplete', // To match it to the existing <label>.
   source: suggest
 })
 ```
 
-Don't forget to include the stylesheet:
+If you want to use it as a replacement for a `<select>` element, read the [Progressive enhancement](#progressive-enhancement) section.
+
+### As a plain JavaScript module
+
+You can copy the [dist/accessible-autocomplete.min.js](dist/accessible-autocomplete.min.js) file to your JavaScript folder and import it into the browser:
 
 ```html
-<link rel="stylesheet" href="node_modules/accessible-autocomplete/dist/accessible-autocomplete.min.css" />
+<script type="text/javascript" href="assets/js/accessible-autocomplete.min.js"></script>
+```
+
+### Styling the autocomplete
+
+A stylesheet is included with the package at [dist/accessible-autocomplete.min.css](dist/accessible-autocomplete.min.css).
+
+You can copy it to your stylesheets folder and import it into the browser:
+
+```html
+<link rel="stylesheet" href="assets/css/accessible-autocomplete.min.css" />
+```
+
+You can also import it using Sass:
+
+```css
+@import "accessible-typeahead";
 ```
 
-### With Preact
+### Using with Preact
 
 If you already use Preact in your application, you can import a bundle that will use that:
 
@@ -81,7 +98,7 @@ preact.render(
 
 [Try out the Preact example!](https://alphagov.github.io/accessible-autocomplete/examples/preact/)
 
-### With React
+### Using with React
 
 If you already use React in your application, you can import a bundle that will use that: