From 439f786cd96f2a26704bae5d269313a1499b8397 Mon Sep 17 00:00:00 2001
From: Ben Smithett <bensmithett@users.noreply.github.com>
Date: Sat, 11 Jul 2020 22:39:46 +1000
Subject: [PATCH] =?UTF-8?q?snake=5Fcase=20=E2=9E=A1=EF=B8=8F=20camelCase/T?=
 =?UTF-8?q?itleCase?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .node-version                                 |   2 +-
 .prettierrc                                   |   7 +++
 .storybook/config.js                          |   2 +-
 app/README.md                                 |  47 ++++++++++++++++++
 app/build.js                                  |   4 +-
 app/{entry.client.js => client.js}            |   6 +--
 .../ExampleComponent.js}                      |  14 +++---
 .../ExampleComponent.stories.js               |   6 +++
 .../ExampleComponent/gunayala.jpg}            | Bin
 .../ExamplePostList.js}                       |   2 +-
 .../ExamplePostList.stories.js}               |   6 +--
 app/components/README.md                      |  12 ++---
 app/components/{global_css.js => cssReset.js} |   2 +-
 .../welcome_banner/welcome_banner.stories.js  |   6 ---
 ...dration_helpers.js => hydrationHelpers.js} |   0
 .../{default_layout.js => DefaultLayout.js}   |   0
 app/layouts/README.md                         |   4 +-
 app/pages/example-post.mdx                    |  16 +++---
 app/pages/index.js                            |  16 ++----
 app/{entry.prerender.js => prerender.js}      |   4 +-
 20 files changed, 103 insertions(+), 53 deletions(-)
 create mode 100644 .prettierrc
 create mode 100644 app/README.md
 rename app/{entry.client.js => client.js} (86%)
 rename app/components/{welcome_banner/welcome_banner.js => ExampleComponent/ExampleComponent.js} (62%)
 create mode 100644 app/components/ExampleComponent/ExampleComponent.stories.js
 rename app/{images/island.jpg => components/ExampleComponent/gunayala.jpg} (100%)
 rename app/components/{post_list/post_list.js => ExamplePostList/ExamplePostList.js} (88%)
 rename app/components/{post_list/post_list.stories.js => ExamplePostList/ExamplePostList.stories.js} (68%)
 rename app/components/{global_css.js => cssReset.js} (72%)
 delete mode 100644 app/components/welcome_banner/welcome_banner.stories.js
 rename app/{hydration_helpers.js => hydrationHelpers.js} (100%)
 rename app/layouts/{default_layout.js => DefaultLayout.js} (100%)
 rename app/{entry.prerender.js => prerender.js} (98%)

diff --git a/.node-version b/.node-version
index 9bbd0cb..d184537 100644
--- a/.node-version
+++ b/.node-version
@@ -1 +1 @@
-12.16.0
+14.5.0
diff --git a/.prettierrc b/.prettierrc
new file mode 100644
index 0000000..b4352dc
--- /dev/null
+++ b/.prettierrc
@@ -0,0 +1,7 @@
+{
+  "printWidth": 120,
+  "quoteProps": "as-needed",
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "none"
+}
diff --git a/.storybook/config.js b/.storybook/config.js
index 2cdcd7e..3cc6226 100644
--- a/.storybook/config.js
+++ b/.storybook/config.js
@@ -2,7 +2,7 @@ import { configure, addDecorator, addParameters } from '@storybook/react'
 import React from 'react'
 import {createRenderer} from 'fela'
 import {RendererProvider} from 'react-fela'
-import {cssReset} from '../app/components/global_css'
+import cssReset from '../app/components/cssReset'
 
 // Setup Fela client runtime
 const renderer = createRenderer({devMode: true})
diff --git a/app/README.md b/app/README.md
new file mode 100644
index 0000000..319f078
--- /dev/null
+++ b/app/README.md
@@ -0,0 +1,47 @@
+# Tropical's 4 core files
+
+## `build.js`
+
+A script run in Node.js that:
+
+- Uses Webpack to compile `prerender.js` and `client.js` so they can run, respectively, in Node.js and the browser.
+- Calls the default export of `prerender.js` to (you guessed it!) prerender your static site.
+
+## `client.js`
+
+The JS file loaded by all pages in a `<script>` tag in the browser.
+
+If using Tropical's `asIsland` helper to enable component hydration, import those components into this file and pass them to `hydrateIslands`.
+
+## `hydrationHelpers.js`
+
+Optional helpers for enabling targeted component [hydration](https://reactjs.org/docs/react-dom.html#hydrate) (see below).
+
+## `prerender.js`
+
+Prerenders your static site:
+
+- Builds a HTML file from every `.js` or `.mdx` page in `pages`
+- Builds a [JSON Feed](https://www.jsonfeed.org/) containing every page with `collection: 'posts'` in its metadata
+
+## Hydration helpers
+
+### `asIsland(componentName, Component, options)`
+
+A [higher order component](https://reactjs.org/docs/higher-order-components.html) that annotates your prerendered components for hydration by `hydrateIslands`.
+
+#### Props
+
+- `componentName`: the name of the component, as configured in `hydrateIslands` *(string, required)*
+- `Component`: any React component whose props can be serialised with `JSON.stringify` *(React component, required)*
+- `options`: *(object)*
+  - `islandTag`: the HTML element to wrap the component with *(string, default: 'div')*
+  - `islandProps`: any props to be passed to the island element *(object, default: {})*
+
+### `hydrateIslands(components)`
+
+Hydrates any components in the browser that were prerendered using `asIsland`.
+
+#### Props
+
+- `components`: an object containing the components to be hydrated *(object, required)*
diff --git a/app/build.js b/app/build.js
index 88cbe8f..94d26c4 100644
--- a/app/build.js
+++ b/app/build.js
@@ -64,7 +64,7 @@ Client JS bundle Webpack config
 const clientConfig = mode => {
   return {
     entry: {
-      client: path.join(__dirname, './entry.client.js')
+      client: path.join(__dirname, './client.js')
     },
     mode,
     module: {
@@ -92,7 +92,7 @@ Prerender JS bundle Webpack config
 const prerenderConfig = (mode) => {
   return {
     entry: {
-      prerender: path.join(__dirname, './entry.prerender.js')
+      prerender: path.join(__dirname, './prerender.js')
     },
     target: 'node',
     node: {
diff --git a/app/entry.client.js b/app/client.js
similarity index 86%
rename from app/entry.client.js
rename to app/client.js
index d7e036e..d06e9e5 100644
--- a/app/entry.client.js
+++ b/app/client.js
@@ -22,15 +22,15 @@ If you remove the following code, the prerendered component won't be hydrated.
 
 import { createRenderer } from 'fela'
 import { rehydrate } from 'fela-dom'
-import { hydrateIslands } from './hydration_helpers'
+import { hydrateIslands } from './hydrationHelpers'
 
 // Hydrate Fela styles
 const felaRenderer = createRenderer()
 rehydrate(felaRenderer)
 
 // Hydrate Tropical islands
-import WelcomeBanner from './components/welcome_banner/welcome_banner'
+import ExampleComponent from './components/ExampleComponent/ExampleComponent'
 
 hydrateIslands({
-  WelcomeBanner
+  ExampleComponent
 }, felaRenderer)
diff --git a/app/components/welcome_banner/welcome_banner.js b/app/components/ExampleComponent/ExampleComponent.js
similarity index 62%
rename from app/components/welcome_banner/welcome_banner.js
rename to app/components/ExampleComponent/ExampleComponent.js
index d86ce8c..8192d2b 100644
--- a/app/components/welcome_banner/welcome_banner.js
+++ b/app/components/ExampleComponent/ExampleComponent.js
@@ -1,7 +1,6 @@
 import React, { useState, useEffect } from 'react'
 import { useFela } from 'react-fela'
-import island from '../../images/island.jpg'
-import {asIsland} from '../../hydration_helpers'
+import image from './gunayala.jpg'
 
 const styles = {
   root: {
@@ -27,7 +26,7 @@ const styles = {
   }
 }
 
-export default function WelcomeBanner ({ alertMessage }) {
+export default function ExampleComponent ({ alertMessage }) {
   const { css } = useFela()
   const [ isMounted, setMounted ] = useState(false)
 
@@ -36,9 +35,9 @@ export default function WelcomeBanner ({ alertMessage }) {
   return (
     <div className={css(styles.root)}>
       <p>
-        Welcome to your <a href='https://github.com/bensmithett/tropical/'>Tropical</a> site!
+        Welcome to your <a href='https://tropical.js.org'>Tropical</a> site!
       </p>
-      <img src={island} alt='Guna Yala, Panama' className={css(styles.img)} />
+      <img src={image} alt='Guna Yala, Panama' className={css(styles.img)} />
       <p>
         <button
           className={css(styles.button)}
@@ -52,4 +51,7 @@ export default function WelcomeBanner ({ alertMessage }) {
   )
 }
 
-export const WelcomeBannerIsland = asIsland('WelcomeBanner', WelcomeBanner)
+// Remember, by default a component is only prerendered.
+// Use a version wrapped with the asIsland() helper to enable hydration in the browser.
+import { asIsland } from '../../hydrationHelpers'
+export const ExampleComponentIsland = asIsland('ExampleComponent', ExampleComponent)
diff --git a/app/components/ExampleComponent/ExampleComponent.stories.js b/app/components/ExampleComponent/ExampleComponent.stories.js
new file mode 100644
index 0000000..15baf63
--- /dev/null
+++ b/app/components/ExampleComponent/ExampleComponent.stories.js
@@ -0,0 +1,6 @@
+import React from 'react'
+import ExampleComponent from './ExampleComponent'
+
+export default { title: 'ExampleComponent' }
+
+export const basic = () => <ExampleComponent alertMessage={'Hello!'} />
diff --git a/app/images/island.jpg b/app/components/ExampleComponent/gunayala.jpg
similarity index 100%
rename from app/images/island.jpg
rename to app/components/ExampleComponent/gunayala.jpg
diff --git a/app/components/post_list/post_list.js b/app/components/ExamplePostList/ExamplePostList.js
similarity index 88%
rename from app/components/post_list/post_list.js
rename to app/components/ExamplePostList/ExamplePostList.js
index 4fc6724..1c796bf 100644
--- a/app/components/post_list/post_list.js
+++ b/app/components/ExamplePostList/ExamplePostList.js
@@ -1,7 +1,7 @@
 import React from 'react'
 import { useFela } from 'react-fela'
 
-export default function PostList ({ posts }) {
+export default function ExamplePostList ({ posts }) {
   const { css } = useFela()
 
   return (
diff --git a/app/components/post_list/post_list.stories.js b/app/components/ExamplePostList/ExamplePostList.stories.js
similarity index 68%
rename from app/components/post_list/post_list.stories.js
rename to app/components/ExamplePostList/ExamplePostList.stories.js
index 22e418a..e8ceeda 100644
--- a/app/components/post_list/post_list.stories.js
+++ b/app/components/ExamplePostList/ExamplePostList.stories.js
@@ -1,10 +1,10 @@
 import React from 'react'
-import PostList from './post_list'
+import ExamplePostList from './ExamplePostList'
 
-export default { title: 'PostList' }
+export default { title: 'ExamplePostList' }
 
 export const basic = () => (
-  <PostList
+  <ExamplePostList
     posts={[
       {
         urlPath: 'post-1',
diff --git a/app/components/README.md b/app/components/README.md
index d827368..227d6f6 100644
--- a/app/components/README.md
+++ b/app/components/README.md
@@ -1,15 +1,15 @@
 # Components
 
-Components are the building blocks that make up your pages and layouts. They're where you define HTML, CSS and (optionally) client-side JS behaviour. Build them quickly in Storybook, then compose them into pages.
+Components are the building blocks that make up your pages and layouts. They're where you define HTML, CSS and (optionally) client-side JS behaviour. Build them quickly in Storybook then compose them into pages.
 
 Tropical components are built with 2 opinionated conventions:
 
-- Style with Fela
+- Style with [Fela](https://fela.js.org/)
 - Opt-in client-side JS
 
 ## Style with Fela
 
-Tropical uses [Fela](https://fela.js.org/) for styling components. See the Fela docs and provided examples, but essentially you write CSS-in-JS that looks like inline styles, which Fela translates into optimised atomic classes:
+Tropical uses [Fela](https://fela.js.org/) for styling components. See the [Fela docs](https://fela.js.org/) for more info, but essentially you write CSS-in-JS that looks like inline styles, which Fela translates into optimised atomic classes:
 
 ```js
 <button className={css({
@@ -24,7 +24,7 @@ Tropical uses [Fela](https://fela.js.org/) for styling components. See the Fela
 
 By default, Tropical components are **only prerendered** and have **no client-side JS behaviour**.
 
-For example, by default this button will appear in the page's prerendered HTML, but nothing will happen when it's clicked.
+For example, this button will appear in the page's prerendered HTML, but by default nothing will happen when it's clicked.
 
 ```js
 const HiButton = () => (
@@ -36,7 +36,7 @@ const HiButton = () => (
 
 ### Progressive enhancement
 
-Prerendered component HTML can be [progressively enhanced](https://en.wikipedia.org/wiki/Progressive_enhancement) in the browser by any client-side JS added to `entry.client.js`.
+Your prerendered HTML can be [progressively enhanced](https://en.wikipedia.org/wiki/Progressive_enhancement) in the browser by any client-side JS added to `client.js`.
 
 ### React component hydration
 
@@ -49,4 +49,4 @@ In many React-based frameworks, the top-level page component is hydrated along w
 
 By contrast, Tropical requires you to **opt specific components in** to hydration (you may of course choose to hydrate your top-level component).
 
-Helpers are provided in `hydration_helpers.js` simplify hydration (though you may hydrate manually in `entry.client.js`).
+Helpers are provided in `hydrationHelpers.js` simplify hydration (though you may hydrate manually in `client.js`).
diff --git a/app/components/global_css.js b/app/components/cssReset.js
similarity index 72%
rename from app/components/global_css.js
rename to app/components/cssReset.js
index 0282401..8fa7a1f 100644
--- a/app/components/global_css.js
+++ b/app/components/cssReset.js
@@ -1,4 +1,4 @@
-export function cssReset (felaRenderer) {
+export default function cssReset (felaRenderer) {
   felaRenderer.renderStatic({
     fontSize: '16px',
     fontFamily: 'sans-serif',
diff --git a/app/components/welcome_banner/welcome_banner.stories.js b/app/components/welcome_banner/welcome_banner.stories.js
deleted file mode 100644
index 99cec2a..0000000
--- a/app/components/welcome_banner/welcome_banner.stories.js
+++ /dev/null
@@ -1,6 +0,0 @@
-import React from 'react'
-import WelcomeBanner from './welcome_banner'
-
-export default { title: 'WelcomeBanner' }
-
-export const basic = () => <WelcomeBanner alertMessage={'An yeel itoe'} />
diff --git a/app/hydration_helpers.js b/app/hydrationHelpers.js
similarity index 100%
rename from app/hydration_helpers.js
rename to app/hydrationHelpers.js
diff --git a/app/layouts/default_layout.js b/app/layouts/DefaultLayout.js
similarity index 100%
rename from app/layouts/default_layout.js
rename to app/layouts/DefaultLayout.js
diff --git a/app/layouts/README.md b/app/layouts/README.md
index 55bbefd..aff6fe6 100644
--- a/app/layouts/README.md
+++ b/app/layouts/README.md
@@ -1,11 +1,11 @@
 # Layouts
 
-Layouts, a concept borrowed from [Rails](https://api.rubyonrails.org/classes/ActionView/Layouts.html), allow you to template the HTML _around_ your page content.
+Layouts allow you to template the HTML _around_ your page content (concept borrowed from [Rails](https://api.rubyonrails.org/classes/ActionView/Layouts.html)).
 
 This could include things like:
 
 - Tags for your `<head>`
-- "Wrapper" divs, or a shared header, footer or sidebar
+- A shared header, footer or sidebar
 
 Unlike Rails, you don't need to directly template your layout's `html`, `head` or `body` tags. Instead, manage those tags with `Helmet` and the Tropical prerender function will put everything in the right place in the final rendered HTML document.
 
diff --git a/app/pages/example-post.mdx b/app/pages/example-post.mdx
index 9ef5922..b4abb7f 100644
--- a/app/pages/example-post.mdx
+++ b/app/pages/example-post.mdx
@@ -19,10 +19,10 @@ If you remove the `collection` and `date` from this file's `meta`, this will jus
 
 MDX lets you render JSX alongside your Markdown, so you can include custom HTML...
 
-import island from '../images/island.jpg'
+import image from '../components/ExampleComponent/gunayala.jpg'
 
 <figure>
-  <img src={island} alt='An island' width={400} />
+  <img src={image} alt='Guna Yala, Panama' width={400} />
   <figcaption>MDX is pretty cool...</figcaption>
 </figure>
 
@@ -30,22 +30,22 @@ import island from '../images/island.jpg'
 
 ... as well as reuse existing components. Note that every page receives the `posts` collection as a prop.
 
-import PostList from '../components/post_list/post_list'
+import ExamplePostList from '../components/ExamplePostList/ExamplePostList'
 
-<PostList posts={props.posts} />
+<ExamplePostList posts={props.posts} />
 
 ---
 
 Remember, components are only prerendered by default.
 
-If you want to automatically rehydrate on the client (aka isomorphic/universal) you'll need to import a component wrapped with the `asIsland` higher order component.
+If you want to automatically [hydrate](https://reactjs.org/docs/react-dom.html#hydrate) a component on the client, you'll need to import a component wrapped with the `asIsland` higher order component.
 
-import WelcomeBanner, { WelcomeBannerIsland } from '../components/welcome_banner/welcome_banner'
+import ExampleComponent, { ExampleComponentIsland } from '../components/ExampleComponent/ExampleComponent'
 
 ## Prerendered only
 
-<WelcomeBanner alertMessage='An yeel itoe' />
+<ExampleComponent alertMessage="This component isn't hydrated, so this alert will never be seen" />
 
 ## Rehydrated
 
-<WelcomeBannerIsland alertMessage='An yeel itoe' />
+<ExampleComponentIsland alertMessage="This component is hydrated, so this alert will be seen" />
diff --git a/app/pages/index.js b/app/pages/index.js
index 932e24e..3354f3b 100644
--- a/app/pages/index.js
+++ b/app/pages/index.js
@@ -7,22 +7,16 @@ export const meta = {
 }
 
 import React from 'react'
-import { Helmet } from 'react-helmet-async'
-import PostList from '../components/post_list/post_list'
+import ExamplePostList from '../components/ExamplePostList/ExamplePostList'
 
-/*
-By default, React components are only used to build your prerendered HTML.
-
-If you want to automatically rehydrate on the client (aka isomorphic/universal) you can
-wrap your original component with the `asIsland` higher order component for use in pages.
-*/
-import { WelcomeBannerIsland } from '../components/welcome_banner/welcome_banner'
+// Note we're importing ExampleComponent wrapped in asIsland, so it will be hydrated in the browser.
+import { ExampleComponentIsland } from '../components/ExampleComponent/ExampleComponent'
 
 export default function IndexPage ({ posts }) {
   return (
     <>
-      <WelcomeBannerIsland alertMessage='Hello!' />
-      <PostList posts={posts} />
+      <ExampleComponentIsland alertMessage='Hello!' />
+      <ExamplePostList posts={posts} />
     </>
   )
 }
diff --git a/app/entry.prerender.js b/app/prerender.js
similarity index 98%
rename from app/entry.prerender.js
rename to app/prerender.js
index 2764bf0..b0c1f6d 100644
--- a/app/entry.prerender.js
+++ b/app/prerender.js
@@ -20,8 +20,8 @@ import { createRenderer } from 'fela'
 import { RendererProvider } from 'react-fela'
 import { renderToMarkup } from 'fela-dom'
 import { Helmet } from 'react-helmet'
-import { cssReset } from './components/global_css'
-import DefaultLayout from './layouts/default_layout'
+import cssReset from './components/cssReset'
+import DefaultLayout from './layouts/DefaultLayout'
 
 export default function prerender (manifest, mode) {
   /*