Clean up documentation and tooling (#387)

Author: davidjgoss

CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Welcome 💖
+
+Before anything else, thank you for taking some of your precious time to help this project move forward. ❤️
+
+If you're new to open source and feeling a bit nervous 😳, we understand! We recommend watching [this excellent guide](https://egghead.io/talks/git-how-to-make-your-first-open-source-contribution) to give you a grounding in some of the basic concepts. We want you to feel safe to make mistakes, and ask questions.
+
+If anything in this guide or anywhere else in the codebase doesn't make sense to you, please let us know! It's through your feedback that we can make this codebase more welcoming, so we'll be glad to hear thoughts.
+
+You can chat with us in the `#committers` channel in our [Community Discord](https://cucumber.io/community#discord), or feel free to [raise an issue](../../issues/new?assignees=&labels=%3Abank%3A+debt&template=developer_experience.md&title=) if you're experiencing any friction trying make your contribution.
+
+## Getting started
+
+First, install the dependencies and check the tests pass:
+
+```shell
+npm install
+npm test
+```
+
+We use [Ladle](https://ladle.dev/) to develop and test our components, which you can start up with:
+
+```shell
+npm run start
+```

README.md

@@ -2,7 +2,8 @@
 
 > A set of React components for rendering Gherkin documents and Cucumber results.
 
-## Screenshot
+Preview and examples:  
+https://cucumber-react-preview.netlify.app/
 
 ![Examples Tables](screenshots/examples-tables.png)
 
@@ -11,35 +12,21 @@
 - This package is distributed in ES module format only.
 - React 18 or above is required.
 
-The source code for screenshots above is:
+The source code for the screenshot above is:
 
 ```jsx
-<EnvelopesWrapper envelopes={envelopes}>
+import { EnvelopesProvider, GherkinDocumentList } from '@cucumber/react-components'
+
+<EnvelopesProvider envelopes={envelopes}>
   <GherkinDocumentList />
-</EnvelopesWrapper>
+</EnvelopesProvider>
 ```
 
-The [`<GherkinDocumentList>`](src/components/app/GherkinDocumentList.tsx) React component,
-is an accordion of [`<GherkinDocument>`](src/components/gherkin/GherkinDocument.tsx).
-
-The `<GherkinDocument>` React component and any component nested within it (such as [`<Scenario>`](src/components/gherkin/Scenario.tsx)) can be rendered standalone.
-
-## `<GherkinDocument>` features
-
-The `<GherkinDocument>` React component is instantiated with a single `gherkinDocument` prop.
-The value must be a [GherkinDocument](../../cucumber-messages/messages.md#io.cucumber.messages.GherkinDocument) object.
-You can use the [Gherkin](../../gherkin) parser to generate a `GherkinDocument` object.
-
-By default the `<GherkinDocument>` component will not display any coloured results, as the `GherkinDocument`
-message object does not contain results, only the [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) of the document. 
-This is fine for simple use cases where results are not important.
-
-To render a `<GherkinDocument>` with results and highlighted [Cucumber Expression parameters](https://cucumber.io/docs/cucumber/cucumber-expressions/) parameters it must be nested inside a 
-[`<Wrapper>`](src/components/app/Wrapper.tsx) component.
+`envelopes` should be an array of [Cucumber Messages](https://github.com/cucumber/messages) that came from a test run. You can obtain these from most Cucumber implementations by using a "Message" formatter.
 
 ## Attachments
 
-Attachments from test runs are shown with their corresponding steps. The baseline behaviour for attachments is a download button. However, we have some special handling for very common MIME types to make them more useful without leaving the report:
+Attachments from test runs are shown with their corresponding steps. The baseline behavior for attachments is a download button. However, we have some special handling for common MIME types to make them more useful without leaving the report:
 
 - `image/*` - images are rendered with an `<img/>` tag
 - `video/*` - videos are rendered with a `<video/` tag
@@ -54,7 +41,7 @@ The standard styling comes without any extra providers or configuration. There a
 
 ### Theming
 
-You can also provide your own theme with a small amount of CSS. Target the element above your highest-level usage of the components:
+You can provide your own theme with a small amount of CSS. Target the element above your highest-level usage of the components:
 
 ```jsx
 <div className="dark-theme">
@@ -136,78 +123,4 @@ Staying with the doc string example, you can use the same `overrides` prop, but
 In each case where you provide your own component, it will receive the same props as the default component, plus two more:
 
 - `styles` - class names for the default styling, so you can still apply these to your custom component if it makes sense
-- `DefaultRenderer` - the default React component, useful if you only want to provide your own rendering for certain cases, and otherwise fall back to the default rendering (don't forget to pass it the props)
-
-## Build / hack
-
-Install dependencies
-
-    npm install
-
-Run tests
-
-    npm test
-
-Interactive development
-
-    npm start
-
-## Ideas
-
-### `ScenarioList` component
-
-A component that renders a list of scenarios (possibly from multiple files, filtered by e.g. tag). 
-
-This component could be used to render relevant scenarios in 3rd-party tools, such as 
-JIRA, Confluence and various issue trackers that support plugins.
-
-### Link to JIRA
-
-Configure with a regexp and url function, and tags will be rendered as JIRA issue links
-
-### Search
-
-Search by tag, but also by text. Could use http://elasticlunr.com/
-or https://lunrjs.com/ - or it could simply perform filtering on an array of `GherkinDocument` messages.
-
-### Search results
-
-Each scenario displayed underneath each other, grouped by feature file. The feature description is "collapsed", 
-(unless it contains the search term) but can be opened.
-
-### Filtering / sorting
-
-* by tag
-* by duration (find slow ones)
-* by status
-* by recency (update timestamp) - exclude old ones
-* by flickeriness
-
-### Tag search
-
-* Render a tag cloud for all tags
-  * Size: count
-  * Color: pass/fail/undefined
-    
-### On-demand data
-
-For large reports (especially with screenshots) it may be too heavy to store it all in the browser.
-The GUI should request data for the current document on demand. The GUI should also be able to filter
-what kind of events it wants. For example, to render the initial screen.
-
-### Server / App
-
-It should be easy to use. Just run the app (Electron). It will create a named pipe where
-it will listen. What's written here gets written straight to the React app (no websocket,
-it's in the same process). This app can be fairly small.
-
-### Rerun tests
-
-Add a message to represent a config+cwd+env for a run, so the GUI can rerun it.
-The config is essentially command line options. They can be modified in the gui.
-Rerun on file change can also be set up. This just makes the whole DX simple.
-
-### Alerts
-
-The app could use the OS to send screen messages (autotest like)
-
+- `DefaultRenderer` - the default React component, useful if you only want to provide your own rendering for certain cases, and otherwise fall back to the default rendering (don't forget to pass it the props)