eddev 0.2.19 → 0.2.22

package/docs_old/docs/gutenberg/3.block-acf.md

@@ -0,0 +1,13 @@
+# Block ACF Fields
+
+Once you've created a `.tsx` file for your block, it'll automatically be registered with WordPress, and is available to be targetted by ACF field groups.
+
+- Create a new ACF Field Group
+- Make sure the block title starts with `Block: ` — this is just convention
+- Add any fields you like.
+
+![Adding an ACF Field Group for a Block](./img/create-acf-fields-for-block.png)
+
+:::tip
+We may add the ability to have [ACF Builder](https://github.com/StoutLogic/acf-builder) support for blocks at some point, however for now it's recommended that you use the ACF Interface to build fields for your blocks. ACF Builder is an advanced tool which requires that you have a deeper knowledge of ACF and all of it's configuration options, and may be harder to use for ACF newbies.
+:::

package/docs_old/docs/gutenberg/4.block-graphql.md

@@ -0,0 +1,63 @@
+# Block GraphQL Files
+
+## Naming
+
+A block named `/blocks/sections/newsletter.tsx` can have a single GraphQL query file named `/blocks/sections/newsletter.graphql`.
+
+Due to a limitation with GraphQL Codegen, each `.graphql` file must contain one uniquely-named.
+
+ACF fields attached to the block can be queried using the naming convention `folderName_blockName`, where the folder name and block name are automatically converted from `dash-case` to `camelCase`.
+
+## Execution
+
+Block queries are executed automatically by PHP code, so there is no need to call any functions to get the data, or handle any loading/error state. The result of the query is sent straight into the `props` of your block.
+
+## Querying ACF Fields
+
+GraphQL schemas for your blocks ACF Fields are automatically generated by PHP.
+
+Consider this block type:
+
+```tsx title="blocks/project/single-project-tile.tsx"
+/**
+ * Title: Single Project Tile
+ * Description: Displays a single project as a large tile.
+ * Category: common
+ * Icon: book-alt
+ * Keywords: post
+ * Types: page, post
+ * Mode: preview
+ * Supports multiple: true
+ */
+import { defineBlock, EditableText, InnerBlocks } from "eddev/blocks"
+
+export default defineBlock("project/single-project-tile", (props) => {
+  return <div>...</div>
+})
+```
+
+With the following ACF field configuration:
+
+![Example block](./img/example-acf-single-project-tile.png)
+
+The ACF fields will be available under `block.project_singleProjectTile`
+
+```graphql title="blocks/project/single-project-tile.graphql"
+query SingleProjectTile {
+  block {
+    project_singleProjectTile {
+      project {
+        ... on Project {
+          id
+          title(format: RENDERED)
+          projectFields {
+            image {
+              ...BasicImage
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```

package/docs_old/docs/gutenberg/5.inline-editing.md

@@ -0,0 +1,33 @@
+# Inline Editing
+
+It's trivial to add inline editing to your blocks. This is totally separate from ACF.
+
+## `<EditableText />`
+
+The most common inline editing function will of course be the ability to edit text in your block. The `<EditableText>` component does just this! Keep in mind, this can only be used on blocks, or components which are used within a block.
+
+```tsx
+<div>
+  <EditableText as="h2" id="title" placeholder="Enter a title" />
+</div>
+```
+
+When the above code runs in the WordPress editor, an author can click on that element and type into it directly.
+
+Note that you can have as many `<EditableText>` components as you want, however each `id` must be unique, since each value is stored as a key/value pair.
+
+The `as` prop is required, and can either be an element type (`p`, `h1`, `h2`, etc.) or a component.
+
+## `useInlineEditableValue`
+
+The `useInlineEditableValue` hook is the foundation of all inline editing in our system — it works a lot like `useState`, except that the content is saved to the block when saving the page, and restored again when the page is loaded.
+
+Much like `EditableText`, the hook requires a unique `id` to identify the value.
+
+You can store any kind of data, including objects and arrays.
+
+```tsx
+const [title, setTitle] = useInlineEditableValue('title');
+
+return <input type="text" value={title} onChange={e => setTitle(e.currentTarget.value)}>
+```

package/docs_old/docs/gutenberg/6.nested-blocks.md

@@ -0,0 +1,80 @@
+# Nested Blocks
+
+Nested blocks add a lot of power to Gutenberg — you can create blocks, which themselves contain more blocks.
+
+The `<InnerBlocks />` component acts as a container for child blocks.
+
+Note that you can only have ONE `InnerBlocks` per-block. This is a WordPress limitation.
+
+## Block Tagging
+
+Most of the time, we want to restrict where blocks can be used. For example, we might have a set of 'root' blocks which the user can only be added to the root of the page. Then, we might want some 'inline' blocks which can be added to some of those root blocks. We may also have specialised blocks, like a 'Button Row', which can only accept 'Button' blocks.
+
+To do this, we've invented a 'tags' system for blocks, which is defined in the comments section of a block.
+
+```tsx
+/*
+ * ...
+ * Tags: root
+ * Child tags: inline
+ */
+```
+
+Use 'Tags' to define the tags on this block, as a comma separated list if defining multiple tags. The `'root'` tag is special, in that any block tagged with it can be added to the root of the page.
+
+If the block has `InnerBlocks`, you can use `Child tags` to indirectly specify the allowed block types which can be added to this block.
+
+## Tagging core blocks
+
+You can also tag core blocks, which are blocks which are included by WordPress, using some PHP code.
+
+Note that you can tag core blocks multiple times with multiple tags.
+
+```php title="backend/blocks.php"
+<?php
+
+  ED()->tagCoreBlocks("wysiwyg", [
+    "core/paragraph",
+    "core/list",
+    "core/heading",
+  ]);
+
+?>
+```
+
+## Putting it all together
+
+For example, if you have a 'Section' block which accepts some WYSIWYG blocks like headings and paragraphs as well as a 'Button Row' block, and only want to allow 'Button' blocks to be added to the 'Button Row', you might have something like this:
+
+```tsx title="blocks/layout/section.tsx"
+/*
+ * ...
+ * Tags: root
+ * Child tags: inline, wysiwyg
+ */
+```
+
+```tsx title="blocks/buttons/button-row.tsx"
+/*
+ * ...
+ * Tags: inline
+ * Child tags: buttons
+ */
+```
+
+```tsx title="blocks/buttons/button.tsx"
+/*
+ * ...
+ * Tags: buttons
+ */
+```
+
+```php title="backend/blocks.php"
+
+  ED()->tagCoreBlocks("wysiwyg", [
+    "core/paragraph",
+    "core/list",
+    "core/heading",
+  ]);
+
+```

package/docs_old/docs/gutenberg/7.restricting-to-post-types.md

@@ -0,0 +1,38 @@
+# Restricting to Post Types
+
+You can restrict an individual block type to only be used in certain post types.
+
+To do this, just update your block's `Types` property. You can have multiple types, separated by commas.
+
+```tsx
+/*
+ * ...
+ * Types: page, post
+ * ...
+ */
+```
+
+### Template Locking
+
+Taking this a step further, you can also specify required root blocks for a post type.
+
+For example, you might want to specify that when creating a new blog post, that only 'Blog Post Header' and 'Blog Post Content' blocks are added to root, and are automatically added when creating a new post, and also cannot be removed.
+
+This needs to be done in PHP:
+
+```php title="backend/blocks.php"
+<?php
+
+  ED()->templateLock([
+    'type' => 'post',
+    'content' => [
+      ['acf/blog-post-header'],
+      ['acf/blog-post-content'],
+    ]
+  ]);
+
+```
+
+:::warning
+Note that you need to use the internal ACF block name when working with template locks. For example, `blog/post-header` becomes `acf/blog-post-header`.
+:::

package/docs_old/docs/gutenberg/8.restricting-to-page-templates.md

@@ -0,0 +1,26 @@
+# Restricting to Page Templates
+
+You can restrict an individual block type to only be used in certain page templates
+
+To do this, just update your block's `Templates` property. You can have multiple templates, separated by commas.
+
+```tsx
+/*
+ * ...
+ * Types: page, post
+ * Templates: templates/my-cool-template
+ * ...
+ */
+```
+
+:::tip
+Be sure to set `Types: page`, otherwise the block wont be available in the page template.
+:::
+
+:::warning
+Note that in above example, the block will be available on all `post`s, and all `page`s which have the template `views/templates/my-cool-template.tsx`.
+:::
+
+### Template Locking
+
+Unfortunately this isn't possible at the moment... mostly due to Gutenberg being a bit crap.

package/docs_old/docs/gutenberg/9.dynamic-blocks.md

@@ -0,0 +1,21 @@
+# Dynamic Blocks
+
+A "dynamic" block is a block that loads asynchronously, only when it's used for the first time. This is useful when a block has a large dependency (think, THREE.js or Swiper). This can drastically reduce the size of your bundle, while also improving the loading time of your site.
+
+The downside is that the block won't load until it's first use, which means that it'll be hidden for a moment while it loads. Because of this, it's recommended that you:
+
+- Perhaps don't use this feature if your block is likely to be used above-the-fold (maybe a good candidate for dynamic components or dynamic imports)
+- Do a fade in animation when the block is first mounted, so that it's not a jarring experience.
+
+It's super easy to enable this feature — just add `Dynamic: true` to your block header comment.
+
+```tsx title="/blocks/layouts/section.tsx"
+/**
+ * Title: TITLE
+ * Description: DESCRIPTION
+ * ...etc
+ * Dynamic: true
+ */
+```
+
+You can read more about dynamic _components_, and other ways to reduce your bundle size here — [Bundle Size Tips →](../how-to/bundle-size)

package/docs_old/docs/gutenberg/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "🧱 Gutenberg Blocks",
+  "position": 4
+}

package/docs_old/docs/how-to/1.new-site.md

@@ -0,0 +1,36 @@
+# Creating a new site
+
+### Initial Setup
+
+1. [Create a new repo on Github](https://github.com/new)
+   1. Set `Owner` to `ed-digital`, and name your repo like `some-client-name`.
+   2. Set `Repository Template` to `ed-digital/eddev-starter-theme`
+   3. Hit `Create repository`
+2. Create a new site in Local, on your computer.
+   1. Use the default settings
+   2. Be sure to use `ed_admin` as the username, and create a secure password using 1pass or similar, and the email address should be `web@ed.com.au`
+   3. Save the username and password to 1pass.
+3. Install the following plugins:
+   1. Advanced Custom Fields Pro ([download](https://www.advancedcustomfields.com/my-account/view-licenses/)
+   2. Add `b3JkZXJfaWQ9NDA3NDN8dHlwZT1kZXZlbG9wZXJ8ZGF0ZT0yMDE0LTA5LTI3IDA4OjUwOjIx` as the key for ACF Pro under 'Custom Fields > Updates'
+   3. Yoast SEO — install from plugins dashboard
+   4. Gutenberg — install from plugins dashboard
+   5. Nested Pages — install from plugins dashboard
+   6. Admin Menu Editor — install from plugins dashboard (use this to hide unused sidebar items, and tidy up the menu for clients.)
+4. Under Settings -> General, remove 'Just another WordPress Site' and set Timezone to Sydney.
+6. Make sure that all the installed plugins have been activated.
+7. Clone your newly created theme to `wp-content/themes/`, making sure that the repo name and the theme folder name are identical.
+8. Run the following commands inside the theme folder
+   1. `composer update`
+   2. `yarn`
+   3. `yarn add --dev eddev`
+   4. `yarn setup`
+9. Activate the theme under Appearance > Themes
+10. Run `yarn dev`
+
+### Initial Flywheel Setup
+
+1. [Create a new site on Flywheel](https://app.getflywheel.com/new-site)
+   1. Select 'My Organisation'
+   2. The username and password are irrelevant, as they'll soon be overridden with your locally created details.
+2. Once complete, restart Local, and do an initial push to the new site, deploying to 'Production' with 'Include Database' selected.

package/docs_old/docs/how-to/2.deployment.md

@@ -0,0 +1,31 @@
+# Deployment
+
+There are some prerequisites for setting up deployment.
+
+1. You've got an SSH key set up on your computer, which has been added to both Github and Flywheel. You only need to do this once for your computer.
+2. You've set up the site on Flywheel already, and completed an initial push using Local Sync.
+
+Assuming the above prerequisites are met, setting up deployment is easy!
+
+1. Grab the Flywheel SSH user for your site.
+   1. On the [Flywheel Dashboard](https://app.getflywheel.com/sites), locate the relevant site.
+   2. Click the 'Advanced' tab.
+   3. Copy the user component from the 'Connect via SSH' section.
+      (For example, if the connection string is `ssh team+ed-digital+the-yards@ssh.getflywheel.com`), the value is `team+ed-digital+the-yards`.
+2. Grab your private key.
+   1. Assuming you're using your default private key, and that it's in the correct format already, you can just run `cat ~/.ssh/id_rsa | pbcopy` in your terminal to copy this directly to your clipboard.
+3. Paste the secrets into the Github repo's 'Secrets' panel.
+   1. Open the repo on Github, and click Settings -> Secrets.
+   2. Add a new secret called `SSH_USER` and paste in the value from step 1. Save it!
+   3. Add a new secret called `PRIVATE_KEY` and paste in the value from step 2. Save it!
+4. Finally, rename `.github/workflows/main.yaml.disabled` to `.github/workflows/main.yaml` and commit/push the results.
+   ```
+   mv .github/workflows/main.yaml.disabled .github/workflows/main.yaml
+   git commit -am "Enable Github Action deployment"
+   git push
+   ```
+5. Monitor the 'Actions' tab on your Github repo page to ensure that the first deployment succeeded.
+
+:::tip warning
+Your first deploy might fail to run at the 'Install Dependencies' step. Try running 'Re-run all jobs'.
+:::

package/docs_old/docs/how-to/3.menus.md

@@ -0,0 +1,72 @@
+# Menus
+
+For simplicities sake, all menus are pre-loaded in the starter theme's `views/_app.graphql`. It looks something like this:
+
+```graphql title="views/_app.graphql"
+query CommonData {
+  menus {
+    nodes {
+      menuItems {
+        nodes {
+          ...MenuItemFields
+        }
+      }
+      locations
+      slug
+      name
+    }
+  }
+}
+
+fragment MenuItemFields on MenuItem {
+  label
+  title
+  target
+  url
+  cssClasses
+  childItems {
+    nodes {
+      label
+      title
+      target
+      url
+      cssClasses
+    }
+  }
+}
+```
+
+The fragment is used there so that it's easy to grab TypeScript types for the menu data structure.
+
+There's also a `backend/menus.php` file, which has a call to `register_nav_menus` function call, which sets up 'menu locations'. If you need more than just one menu, you can add them there.
+
+```php
+register_nav_menus([
+  'main' => 'Main Menu',
+  'footer' => 'Footer Menu'
+]);
+```
+
+The starter theme also comes with a `components/atoms/Menu.tsx` component. It's included as a component which you can tailor to your needs.
+
+To use the menu component, you'll need to specify the menu location which you defined in PHP. Assuming you've got `yarn dev` running, the menu locations will auto-complete with TypeScript.
+
+```tsx
+<Menu location="Main">
+```
+
+It's recommended that if you need to stylise or customise the Menu, that you kinda keep that file nice and generic, and create a new component which uses the `Menu` component as a base. (Or alternatively, you can always copy/paste the `Menu` code into your new component.)
+
+```tsx title="components/atoms/MyCoolMenu.tsx
+import { Menu } from "@components/atoms/Menus"
+
+export const MyCoolMenu = styled(Menu, {
+  display: "flex",
+  li: {
+    marginLeft: "20px",
+    a: {
+      fontFamily: '"Comic Sans"',
+    },
+  },
+})
+```

package/docs_old/docs/how-to/4.options-pages.md

@@ -0,0 +1,41 @@
+# Options Pages
+
+You can create an 'Options Page' on the WordPress sidebar to create a space for global ACF fields.
+
+Creating and consuming an options page can be completed in a few steps:
+
+1. Create a new Options Page — check out `backend/options.php` for some example code, noting that `show_in_graphql` must be set to `true`.
+2. Create a new ACF field group, with the fields you need.
+   1. Set the Location Rule to `Options Page` `is equal to` `<your new options page>`.
+   2. Make sure `Show in GraphQL` is checked.
+   3. Set `GraphQL Field Name` to something short and sweet, using pascalCase, eg `myOptions`.
+3. Check the GraphiQL IDE, and look for a root-level field with a similar name to the `menu_slug` defined in your PHP, code, eg. `themeGeneralSettings`. It should have a child field with you `GraphQL Field Name`, which contains your settings!
+
+The PHP code should look something like this:
+
+```php
+acf_add_options_page([
+  'page_title' 	=> 'Theme Settings',
+  'menu_title'	=> 'Theme Settings',
+  'menu_slug' 	=> 'theme-general-settings',
+  'capability'	=> 'edit_posts',
+  'redirect'		=> false,
+  'show_in_graphql' => true
+]);
+```
+
+Assuming that all worked, you can then query these fields in an `.graphql` file. If it needs to be globally accessible, you can add it to the `_app.graphql` file, and access it using the `useAppData` hook. It'll even be typed with TypeScript.
+
+```graphql title="views/_app.graphql"
+query AppData {
+  themeGeneralSettings {
+    myOptions {
+      footerText
+    }
+  }
+}
+```
+
+```tsx
+const footerText = useAppData((data) => data?.themeGeneralSettings?.myOptions?.footerText)
+```

package/docs_old/docs/how-to/5.bundle-size.md

@@ -0,0 +1,177 @@
+# Bundle Size Tips
+
+## Inspecting Bundle Size
+
+You can quite easily see the production size of your app by running:
+
+```bash
+yarn build
+```
+
+![Webpack Result](./img/bundle-webpack-before.png)
+
+Above, we can see that the bundle size is 1.34mb, which is quite large. The note from Webpack says that we should aim for 244kb, which is really quite small. When we eventually move to serverless (via Vercel) for production frontends, we'll certainly aim for this smaller size. For now, with WordPress hosting, 600-700kb is fine. React itself takes up a bit of space on it's own.
+
+Let's dig deeper into why the bundle is so large.
+
+Our compile system includes the official [Webpack Bundle Analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer) plugin. You can get a detailed analysis of the bundle size using the following:
+
+```bash
+yarn build
+open dist/frontend/bundle-report.html
+```
+
+Your browser will launch the bundle report, which will look something like this.
+
+![Bundle Size Output](./img/bundle-analysis-before.png)
+
+You can see in the example above, that `hls.js` and `moment` + `moment-timezone` are taking up _a lot_ of the bundle size.
+
+What can we do about this?
+
+## Choosing better libraries
+
+In the example above, `moment` is taking up SO much space, for something that is so simple. There are much simpler and smaller libraries that can be used instead.
+
+- If all you want is date formatting, check out `date-fns` — which provides a nifty date formatting function. The library is tree-shakable, meaning only the functions from that library you actually use in your code will be included in the bundle. [date-fns →](https://date-fns.org/)
+- If you need something a little more powerful, or if you need something related to timezones, check out `luxon`, which is made by the same team that created `moment`. It's a much lighter alternative, because even though it supports timezones, it uses native browser APIs, instead of bundling info on every timezone/locale. [Luxon →](https://moment.github.io/luxon/index.html#/?id=luxon)
+  - (ps. Luxon doesn't come with TypeScript types, but you can install them using `yarn add --dev @types/luxon`)
+
+It's always worth reconsidering the libraries we choose, looking for the most modern libraries for certain functions.
+
+## Dynamic imports
+
+Next up is `hls.js`. It's a library that provides a simple way to load and play HLS streams. It's not huge, but we probably don't need to include it in the main bundle.
+
+Say we have the following code:
+
+```tsx
+import Hls from "hls.js"
+
+// ...
+
+useEffect(() => {
+  const video = ref.current!
+  if (src) {
+    if (video.canPlayType("application/vnd.apple.mpegurl")) {
+      // HLS is already supported natively by this browser
+      video.src = props.url
+    } else {
+      // HLS is not supported by the browser. Use Hls.js instead!
+      const hls = new Hls()
+      hls.loadSource(props.url!)
+      hls.attachMedia(video)
+      return () => {
+        hls.destroy()
+      }
+    }
+  }
+}, [src])
+```
+
+We can quite easily refactor this code to use dynamic imports, which will automatically split that library into it's own file, which will be imported separately only if/when it's needed. If we still need TypeScript types for the module, we can also use `import type` syntax, which will only import the types for TypeScript's sake, and not the module itself.
+
+```tsx
+import type Hls from "hls.js"
+
+// ...
+
+useEffect(() => {
+  const video = ref.current!
+  if (props.url) {
+    if (video.canPlayType("application/vnd.apple.mpegurl")) {
+      // HLS is already supported natively by this browser
+      video.src = props.url
+    } else {
+      // HLS is not supported by the browser. Use Hls.js instead!
+      // Declare a reference to the object, so we can can still destroy it when the component transitions out
+      let hls: Hls
+      import("hls.js").then(({ default: Hls }) => {
+        // hls.js has been successfully dynamically imported.
+        // Assign to the `hls` variable, so that it can be destroyed properly
+        hls = new Hls()
+        hls.loadSource(props.url!)
+        hls.attachMedia(video)
+      })
+      return () => {
+        // Destroy the hls video, as long as it was created in the first place
+        if (hls) {
+          hls.destroy()
+        }
+      }
+    }
+  }
+}, [props.url])
+```
+
+## Dynamicly imported components
+
+Similar to Next's `next/dynamic` [(link)](https://nextjs.org/docs/advanced-features/dynamic-import), we have our own `eddev/dynamic` function. This allows you dynamically load components from the `components/*` directory using dynamic imports.
+
+```tsx title="blocks/homepage/some-block.tsx"
+import { dynamic } from "eddev/dynamic"
+
+const MyDynamicComponent = dynamic(() => import("@components/something/my-dynamic-component"))
+
+export default defineBlock("homepage/some-block", () => {
+  return (
+    <div>
+      <p>I appear instantly</p>
+      <MyDynamicComponent fallback={<div>Loading...</div>} />
+    </div>
+  )
+})
+```
+
+All the same props from `MyDynamicComponent` are available, and the fallback (which is optional) is added as a prop by the `dynamic` function. It'll show the fallback while the component is loading.
+
+When using this feature, you may notice a flash while the component is being loaded, since your page will actually render without the dynamic component first. This means that it may not always be suitable if the component is typically "above the fold". You may want to consider showing a placeholder div, and/or fading in the component using an animation once it's loaded.
+
+It's also important to note that the dynamic function expects (by default), a `default` export. Normally, we prefer to export named components, but in this case, `default` is good.
+
+```tsx title="components/something/my-dynamic-component.tsx"
+// BAD: export function MyDynamicComponent() {}
+// GOOD:
+export default function MyDynamicComponent() {
+  return <div>I'm a dynamic component!</div>
+}
+```
+
+Internally, we use `@loadable/components` — you can see other options for `dynamic` via their [docs](https://loadable-components.com/). Next also uses this library!
+
+## Dynamically imported blocks
+
+The `eddev/dynamic` function requires a tiny bit of boilerplate to get going. If you'd like to make a whole _block_ load dynamically, it's even easier. Note though that you wont be able to show a loading fallback.
+
+Just add `Dynamic: true` to your block header comment — the compiler will spot this, and automatically turn it into a dynamic component. That's it!
+
+```tsx title="blocks/homepage/some-block.tsx"
+/**
+ * Title: Some Block
+ * Description: A block that does something cool
+ * Category: common
+ * Icon: book-alt
+ * Keywords: post
+ * Templates: default
+ * Types: page
+ * Mode: preview
+ * Supports multiple: true
+ * Tags: root
+ * Child Tags: none
+ * Dynamic: true
+ */
+```
+
+^ The last line is the important part. You can read more about dynamic blocks [here](../gutenberg/dynamic-blocks).
+
+## Validating the changes
+
+In the top sections above, we swapped from `moment` to `luxon`, and we also made `hls.js` a dynamic import.
+
+After running `yarn build` again, and checking out the visualizer, we can see that these two small changes have reduced our main bundle size by **HALF**.
+
+![Webpack Result](./img/bundle-webpack-after.png)
+
+![Bundle Size Output](./img/bundle-analysis-after.png)
+
+We could take this even further if we wanted, by making any blocks which use Swiper dynamic blocks, as discussed above.