feat: modernize the library

Author: GeorgeGkas

CONTRIBUTING.md

@@ -10,14 +10,6 @@
 
 - `npm start` will run the app's demo folder at [http://localhost:3000](http://localhost:3000) with hot module reloading.
 
-## Running Tests
-
-- `npm test` will run the tests once.
-
-- `npm run test:coverage` will run the tests and produce a coverage report in `coverage/`.
-
-- `npm run test:watch` will run the tests on every change.
-
 ## Building
 
 - `npm run build` creates a production build by default.

README.md

@@ -1,38 +1,54 @@
 # super-react-gist
 Simple and flexible component that allows you to embed [GitHub Gists](https://gist.github.com/) in [React](https://reactjs.org/) projects.
 
-
 ## Features
 - Embed a **single file** from Gist repository!
 - Embed **multiple files** from multiple Gist repositories!
 - Embed the **whole Gist** repository!
 - **Easy usage**: Just copy-paste the Gist's repository URL to embed the whole repository, or copy-paste the permalink of an individual file to include just that.
+- Maximize Development Experience with **custom error handling**.
 - **Lightweight**: ~9KB minified (~4kb if gzipped).
 - Packaged as **UMD module** that can be loaded everywhere.
 - **Works both on secret and public repositories**.
 
 ## Table of contents
-- [Quick Start](#quick-start)
-- [Usage](#usage)
+- [Installation](#installation)
+- [Component Properties](#component-properties)
 - [Examples](#examples)
 - [Browser Support](#browser-support)
 - [Bugs and feature requests](#bugs-and-feature-requests)
 - [Contributing](#contributing)
-- [Creator](#creator)
-- [Licence](#license)
+- [License](#license)
 
-## Quick Start
-- Clone the repo: `git clone https://github.com/georgegkas/super-react-gist.git`
-- Install with [npm](https://www.npmjs.com/): `npm install --save super-react-gist`
+## Installation
+### Through NPM
+To install through npm run:
 
-## Usage
-**`<Gist url={string} file={string} />`**
-- `url` *{ string }* **required** The URL of the Gist repository or the permalink of an individual gist file.
-- `file` *{ string }* Name of a specific file to include.
+```bash
+npm i super-react-gist
+```
+### As UMD module
+**super-react-gist** comes as UMD module. This means you are able to use  **super-react-gist** component in your browser!
 
+To get started add the following script tag in your html file:
+
+```html
+<script src="https://unpkg.com/super-react-gist/umd/super-react-gist.min.js"></script>
+```
+
+## Component Properties
+
+| Name | Type | Required | Description |
+| :--- | :--- | :---: | :--- |
+| `url` | *string* |✅ | The URL of the Gist repository or the permalink of an individual gist file. |
+| `file` | *string* | | Optional filename to include. |
+| `onLoad` | *function* | | Optional callback triggered on Gist load. |
+| `onError` | *function* | | Optional callback triggered on fetch error. |
+| `LoadingComponent` | *Component* | | Optional React component to render on Gist loading. |
+| `ErrorComponent` | *Component* || Optional React component to render if Gist fetch fails. |
 
 ## Examples
-The following examples illustrate some basic usages of **super-react-gist** component.
+The following examples illustrate some basic features of the **super-react-gist** library.
 
 ### Render one file
 With **super-react-gist** you are able to render a single file from a gist repository.
@@ -42,36 +58,28 @@ With **super-react-gist** you are able to render a single file from a gist repos
 import React from 'react'
 import Gist from 'super-react-gist' // <-- import the library
 
-class MyComponent extends React.Component {
-  render() {
-    return (
-      <div>
-        <p>Just enter the file permalink to <em>url</em> prop.</p>
-        <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-start-js' />
-      </div>
-    )
-  }
-}
+const MyComponent = () => (
+  <div>
+    <p>Just enter the file permalink to <em>url</em> prop.</p>
+    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-start-js' />
+  </div>
+)
 ```
 
 ### Render multiple files
-You are not restricted to use only one **super-react-gist** component in your project.
+You are not restricted to use only one **Gist** component in your project.
 
 ```javascript
 import React from 'react'
 import Gist from 'super-react-gist' // <-- import the library
 
-class MyComponent extends React.Component {
-  render() {
-    return (
-      <div>
-        <p>Rendering multiple files is a piece of cake!</p>
-        <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-start-js' />
-        <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-multiple-js' />
-      </div>
-    )
-  }
-}
+const MyComponent = () => (
+  <div>
+    <p>Rendering multiple files is a piece of cake!</p>
+    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-start-js' />
+    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-multiple-js' />
+  </div>
+)
 ```
 
 ### Render using `file` prop
@@ -86,20 +94,16 @@ This is how we do it:
 import React from 'react'
 import Gist from 'super-react-gist'
 
-class MyComponent extends React.Component {
-  render() {
-    return (
-      <div>
-        <p>provide the Gist url without including the file.</p>
-        <p>...and pass the filename to `file` prop.</p>
-        <Gist
-        url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df'
-          file='CaMelCase.js'
-          />
-      </div>
-    )
-  }
-}
+const MyComponent = () => (
+  <div>
+    <p>provide the Gist url without including the file.</p>
+    <p>...and pass the filename to `file` prop.</p>
+    <Gist
+      url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df'
+      file='CaMelCase.js'
+      />
+  </div>
+)
 ```
 
 ### Render the whole Gist
@@ -109,40 +113,82 @@ Of course, we can also embed the whole Gist repository just by copying the Gist
 import React from 'react'
 import Gist from 'super-react-gist'
 
-class MyComponent extends React.Component {
-  render() {
-    return (
-      <div>
-        <p>provide the Gist URL without include any file.</p>
-        <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df' />
-      </div>
-    )
-  }
-}
+const MyComponent = () => (
+  <div>
+    <p>provide the Gist URL without include any file.</p>
+    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df' />
+  </div>
+)
+```
+
+### Use a custom loading component
+Most of the times, we would like to render a custom React component while our Gists are loading.
+
+```javascript
+import React from 'react'
+import Gist from 'super-react-gist'
+
+const MyComponent = () => (
+  <div>
+    <p>provide the Gist URL without include any file.</p>
+    <Gist 
+      url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df' 
+      LoadingComponent={() => <div>Waiting for Gist...</div>}
+    />
+  </div>
+)
+```
+
+### Use a custom error component
+In case that fetching fails, we can render a custom React Component to indicate the error.
+
+```javascript
+import React from 'react'
+import Gist from 'super-react-gist'
+
+const MyComponent = () => (
+  <div>
+    <p>provide the Gist URL without include any file.</p>
+    <Gist 
+      url='https://gist.github.com/GeorgeGkas/NOT_EXIST' 
+      ErrorComponent={() => <div>Could not fetch component</div>}
+    />
+  </div>
+)
+```
+
+### Listen to error and loading events
+Apart from providing a custom error or loading component, we can also register the corresponding callbacks. The `onLoad` callback is executed when the Gist is fetched successfully, while `onError` callback is executed if could not retrieve the requested Gist.
+
+```javascript
+import React from 'react'
+import Gist from 'super-react-gist'
+
+const MyComponent = () => (
+  <div>
+    <p>provide the Gist URL without include any file.</p>
+    <Gist 
+      url='https://gist.github.com/GeorgeGkas/NOT_EXIST' 
+      οnLoad={() => console.log('Gist fetched successfully!')}
+      onError={() => console.log('Gist could not be fetched!')}
+    />
+  </div>
+)
 ```
 
 ### Combine all the above techniques
 *This example is left as an exercise to the reader.*
 
 
 ### Run the examples yourself
-Clone the repository and then run:
+Clone the repo `git clone https://github.com/georgegkas/super-react-gist.git` and then run:
+
 ```
 $ npm install
-$ npm run build
 $ npm start
 ```
 
-## Browser Support
-**super-react-gist** comes as UMD module. This means you are able to use  **super-react-gist** component in your browser!
-
-To get started add the following script tag in your html file:
-
-```html
-<script src="https://unpkg.com/super-react-gist/umd/super-react-gist.min.js"></script>
-```
-
-Then you are able to access **super-react-gist** component using the `Gist` name, which is the global variable the UMD build has exported. [See this Pen for a demonstration](https://codepen.io/georgegkas/pen/zpzMzz).
+Then you are able to access the `Gist` component using the `Gist`  global variable. [See this Pen for a demonstration](https://codepen.io/georgegkas/pen/zpzMzz).
 
 ## Bugs and feature requests
 Have a bug or a feature request? [Please open a new issue](https://github.com/georgegkas/super-react-gist/issues).
@@ -152,11 +198,5 @@ Please read through our contributing guidelines in [CONTRIBUTING.md](https://git
 
 Editor preferences are available in the editor config for easy use in common text editors. Read more and download plugins at [http://editorconfig.org](http://editorconfig.org).
 
-## Creator
-George Gkasdrogkas
-
-- [https://github.com/georgegkas](https://github.com/georgegkas)
-- [https://codepen.io/georgegkas](http://codepen.io/georgegkas)
-
-## Licence
-Code released under the [MIT License](https://opensource.org/licenses/MIT).  See [LICENSE.md](https://github.com/georgegkas/super-react-gist/blob/master/LICENSE.md) for more details.
+## License
+Code released under the [MIT License](https://opensource.org/licenses/MIT). See [LICENSE.md](https://github.com/georgegkas/super-react-gist/blob/master/LICENSE.md) for more details.

demo/src/index.js

@@ -1,7 +1,7 @@
 import React from 'react'
 import ReactDom from 'react-dom'
 
-import Gist from '../../src'
+import Gist from '../../src/index'
 
 const Demo = () => (
   <div>
@@ -10,24 +10,28 @@ const Demo = () => (
     <p>This demo illustrate a basic usage of <strong>super-react-app</strong> component.</p>
     <h2>Render one file</h2>
     <p>With <strong>super-react-app</strong> you are able to render a single file from a gist repository.</p>
-    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-start-js' />
+    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-start-js' LoadingComponent={() => <strong>Custom loading component...</strong>} />
     <h2>Render multiple files</h2>
     <p>You are not restricted to use only one <strong>super-react-app</strong> component in your project. </p>
-    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-start-js' />
-    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-multiple-js' />
+    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-start-js' LoadingComponent={() => <strong>Custom loading component...</strong>} />
+    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df#file-multiple-js' LoadingComponent={() => <strong>Custom loading component...</strong>} />
     <h2>Render using <code>file</code> prop</h2>
     <p>Works both on <strong>public</strong> and <strong>secret</strong> gists.</p>
     <p>Oh snap! *face-palm*! In case you didn't notice we can only use the above method to render files that do not contain any uppercase letter. For instance, if our Gist repo contains a file <code>CaMelCase.js</code>, then providing just the permalink will not work!</p>
     <p><strong>Q</strong>: How can we render this <code>CaMelCase.js</code> file?</p>
     <p><strong>A</strong>: By providing a <code>file</code> prop to our <code>Gist</code> component to indicate which file we want to include.</p>
     <p>This is how we do it:</p>
-    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df' file='CaMelCase.js' />
+    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df' file='CaMelCase.js' LoadingComponent={() => <strong>Custom loading component...</strong>} />
     <h2>Render the whole Gist</h2>
     <p>Of course, we can also embed the whole Gist repository just by copying the Gist URL.</p>
-    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df' />
+    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b766934ffe802d30df' LoadingComponent={() => <strong>Custom loading component...</strong>} />
+    
+    <h2>Error Component</h2>
+    <p>Render a custom error component if Gist could not be retrieved.</p>
+    <Gist url='https://gist.github.com/GeorgeGkas/5f55a83909a3f5b7tyjty66934ffedd802d30df#file-multiple-js' LoadingComponent={() => <strong>Custom loading component...</strong>} ErrorComponent={() => <strong>Gist failed to load.</strong>} />
+    
     <h2>Combine all the above techniques</h2>
     <p><em>This example is left as an exercise to the reader.</em></p>
-    {/* Type here */}
   </div>
 )