feat: Introduce styleguide. (#185)

Author: Matthias Wagler

.eslintignore

@@ -1,2 +1,5 @@
+styleguide/out
+styleguide/.next
+
 test/shared/sampleApplication/out
 test/shared/sampleApplication/.next

.npmignore

@@ -1,3 +1,4 @@
 .dependabot
 .github
 test/
+styleguide/

README.md

@@ -11,59 +11,35 @@ thenativeweb-ux provides UI components for the native web applications.
 | Dev dependencies | ![David](https://img.shields.io/david/dev/thenativeweb/thenativeweb-ux)                                                                                    |
 | Build            | ![GitHub Actions](https://github.com/thenativeweb/thenativeweb-ux/workflows/Release/badge.svg?branch=master) |
 | License          | ![GitHub](https://img.shields.io/github/license/thenativeweb/thenativeweb-ux)                                                                              |
-
 ## Installation
 
 ```shell
-$ npm install thenativeweb-ux
+$ npm install thenativeweb-ux react react-dom next
 ```
 
-## Quick start
-
-First you need to add a reference to your application. For a minimum setup, you have to reference the components `Application` and `ThemeProvider`:
+## Viewing the documentation
 
-```javascript
-import { Application, ThemeProvider } from 'thenativeweb-ux';
-```
+For application developers there is a [styleguide](styleguide) that serves as the documentation of this module. It contains a quick start, and showcases all the available components. To run it on your local machine clone this repository, install its dependencies, and run the following command:
 
-Then, inside your application's `render` function, setup the basic structure by wrapping the `Application` component inside a `ThemeProvider`.:
-
-```jsx
-<ThemeProvider>
-  <Application>
-    {
-      // ...
-    }
-  </Application>
-</ThemeProvider>
+```shell
+$ npm run start-styleguide
 ```
 
-By default, the `ThemeProvider` will create a _the native web_ theme, but you can also select other themes. Currently, the following themes are available:
-
--   `thenativeweb`
--   `wolkenkit`
-
-### Using components
-
-Besides setting up the application itself, you may also use a variety of components. To use a component, you need to add a reference to it. E.g., to use the `Button` component, add the following line to your code:
-
-```javascript
-import { Button } from 'thenativeweb-ux';
-```
+Then point your browser to `http://localhost:6060/`.
 
-### Viewing the Next.js sample application
+## Viewing the Next.js sample application
 
-The integration tests include a [Next.js sample application](test/shared/sampleApplication) that shows how the various components can be used from within a Next.js project. To run the sample application use the following command:
+The integration tests include a [Next.js sample application](test/shared/sampleApplication) that shows how components can be used from within a Next.js project. To run the sample application use the following command:
 
 ```shell
 $ npm run start-sample-application
 ```
 
-### Debugging integration tests
+## Debugging integration tests
 
 This project uses [puppeteer](https://github.com/GoogleChrome/puppeteer) to verify that components render correctly inside a browser. By default these tests are run in headless mode. As debugging integration tests in headless mode can be painful there are two options to debug integration tests visually.
 
-#### Viewing failing test pages in a browser
+### Viewing failing test pages in a browser
 
 First, to debug a failing integration test, you can have a look at the failing test page in a browser without running the tests. For that run the sample application using the following command:
 
@@ -73,7 +49,7 @@ $ npm run start-sample-application
 
 Then point your browser to the failing test page and verify if it renders correctly.
 
-#### Running tests with a UI and in slow motion
+### Running tests with a UI and in slow motion
 
 Second, verifying that all the puppeteer commands are executed succesfully, it is much easier to do when puppeteer is not running in headless mode. To disable headless mode, set the environment variable `DEBUG` to `true`. This will start puppeteer in non-headless mode and slow down each operation:
 

lib/components/animation/Transition/Documentation.tsx

@@ -0,0 +1,67 @@
+import { ComponentPreview } from '../../../components/documentation/ComponentPreview';
+import { DropdownOption } from '../../input/Dropdown';
+import { TransitionType } from './TransitionType';
+import { types } from './types';
+import { CheckBox, ControlGroup, ControlGroupItem, Dropdown, Form, Headline, Paragraph, Transition } from '../../..';
+import React, { ReactElement, useState } from 'react';
+
+const transitionTypes = Object.keys(types).map((type): DropdownOption => ({ label: type, value: type }));
+
+const Documentation = (): ReactElement => {
+  const [ isBoxVisible, setIsBoxVisible ] = useState(true);
+  const [ type, setType ] = useState(transitionTypes[0].value);
+
+  return (
+    <React.Fragment>
+      <Headline>Transition</Headline>
+
+      <Paragraph>
+        Transition is a component for animating a single element while it enters
+        or leaves your application. There&apos;s a set of built-in types you can
+        use: <code>Fade</code>, <code>FadeInLeft</code>, <code>FadeInRight</code>, <code>Grow</code> and <code>Zoom</code>.
+        Wrap the component that should be animated and use the
+        boolean <code>in</code> property to animate in and out. Please note that
+        you might have to set explicit dimensions to the parent of the animated
+        component in order to prevent a page jumps.
+      </Paragraph>
+
+      <ComponentPreview>
+        <React.Fragment>
+          <Form>
+            <ControlGroup>
+              <ControlGroupItem label='Transition type'>
+                <Dropdown
+                  value={ type }
+
+                  options={ transitionTypes }
+                  onChange={ (value: string): void => setType(value) }
+                />
+              </ControlGroupItem>
+            </ControlGroup>
+            <ControlGroup>
+              <ControlGroupItem label='Show box'>
+                <CheckBox onChange={ (): void => setIsBoxVisible(!isBoxVisible) } id='checkbox-is-box-visible' />
+              </ControlGroupItem>
+            </ControlGroup>
+          </Form>
+
+          <div style={{ width: 200, height: 200 }}>
+            <Transition type={ type as TransitionType } in={ isBoxVisible }>
+              <div
+                style={{
+                  width: 200,
+                  height: 200,
+                  background: 'deeppink'
+                }}
+              >
+                This box will be animated using {type}.
+              </div>
+            </Transition>
+          </div>
+        </React.Fragment>
+      </ComponentPreview>
+    </React.Fragment>
+  );
+};
+
+export { Documentation };

lib/components/animation/Transition/README.md

@@ -8,7 +8,7 @@ const handleEnter = function (node: HTMLElement): void {
   anime({
     targets: node,
     opacity: [ 0, 1 ],
-    duration: defaults.duration,
+    duration: 600,
     easing: defaults.easing
   });
 };
@@ -17,7 +17,7 @@ const handleExit = function (node: HTMLElement): void {
   anime({
     targets: node,
     opacity: [ 1, 0 ],
-    duration: defaults.duration,
+    duration: 600,
     easing: defaults.easing
   });
 };
@@ -31,7 +31,7 @@ const Fade: FunctionComponent<TransitionProps> = ({ children, key, in: fadeIn })
     unmountOnExit={ true }
     onEnter={ handleEnter }
     onExit={ handleExit }
-    timeout={ defaults.duration }
+    timeout={ 600 }
   >
     { children }
   </Transition>

lib/components/animation/Transition/types/Fade.tsx

@@ -0,0 +1,60 @@
+import { ComponentPreview } from '../../../components/documentation/ComponentPreview';
+import { Button, Headline, Paragraph, TransitionGroup } from '../../..';
+import React, { ReactElement, useState } from 'react';
+
+const Documentation = (): ReactElement => {
+  const [ items, setItems ] = useState([ 'Thing 1' ]);
+
+  const addItem = (): void => {
+    const newItems = [ ...items, `Thing ${items.length + 1}` ];
+
+    setItems(newItems);
+  };
+
+  const removeItem = (): void => {
+    const newItems = items.slice(0, -1);
+
+    setItems(newItems);
+  };
+
+  return (
+    <React.Fragment>
+      <Headline>TransitionGroup</Headline>
+
+      <Paragraph>
+        To transition an array of elements, use
+        the <code>TransitionGroup</code> component. Please note that you have to
+        set a unique key for each item in order to let React know which element
+        has been added or removed.
+      </Paragraph>
+
+      <ComponentPreview>
+        <React.Fragment>
+          <div style={{ display: 'flex' }}>
+            <Button onClick={ addItem }>Add item</Button>
+            <Button onClick={ removeItem }>Remove item</Button>
+          </div>
+          <TransitionGroup type='FadeInRight'>
+            { items.map((item): ReactElement => (
+              <div
+                style={{
+                  width: 100,
+                  height: 100,
+                  float: 'left',
+                  background: 'deeppink',
+                  marginRight: 20,
+                  marginTop: 20
+                }}
+                key={ item }
+              >
+                {item}
+              </div>
+            )) }
+          </TransitionGroup>
+        </React.Fragment>
+      </ComponentPreview>
+    </React.Fragment>
+  );
+};
+
+export { Documentation };