From 2ea638909de44189be177442a9f7f280726e26db Mon Sep 17 00:00:00 2001
From: James Young <hello@jamesyoung.ch>
Date: Fri, 16 Sep 2022 18:19:55 +0200
Subject: [PATCH] docs: add how-to docs for creating components (#2124)

* docs: add HOW-TO docs for creating components

* Prettified Code!

Co-authored-by: jamescallumyoung <jamescallumyoung@users.noreply.github.com>
---
 web/README.md                       |  2 +
 web/components/_COMPONENT_HOW_TO.md | 73 +++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 web/components/_COMPONENT_HOW_TO.md

diff --git a/web/README.md b/web/README.md
index 26e8b1542..2b35a6121 100644
--- a/web/README.md
+++ b/web/README.md
@@ -28,6 +28,8 @@ isolation.
 1. If no design exists, then you can ask around the Owncast chat for help, for come up with your own ideas!
 1. No designs are stuck in stone, and we're using this as an opportunity to level up the UI of Owncast, so all ideas are welcome.
 
+See the extra how-to guide for components here: [Components How-to](./components/_COMPONENT_HOW_TO.md).
+
 ### Run the web project
 
 Make sure you're running an instance of Owncast on localhost:8080, as your copy of the admin will look to use that as the API.
diff --git a/web/components/_COMPONENT_HOW_TO.md b/web/components/_COMPONENT_HOW_TO.md
new file mode 100644
index 000000000..db517bfd0
--- /dev/null
+++ b/web/components/_COMPONENT_HOW_TO.md
@@ -0,0 +1,73 @@
+# How we develop components
+
+This document outlines how we develop the components for the Owncast Web UI.
+
+You should use this document as a guide when making changes to existing components, and adding new ones.
+Working with the same development process help keep the project maintainable.
+
+## What are components
+
+A component in React is a custom HTML element. They're included in the DOM just like regular elements `<ChatBox /`>.
+
+## Functional Components
+
+In react, there's two ways to write a component: there's Class-based Components, and Functional Components.
+
+Class-based is older and has fallen out of favor.
+Functional Components are the new standard and you'll find them in most React projects written today.
+
+See the [React Functional Component docs](https://reactjs.org/docs/components-and-props.html) for more info.
+
+### How we write Functional Components
+
+We've defined a pattern for how we write Functional Components in the Owncast Web UI.
+There's a few ways to to write Functional Components that are common, so defining a standard helps keep this project readable and consistent.
+
+The pattern we've settled on is:
+
+**For stateless components:**
+
+```tsx
+export type MyNewButtonProps = {
+  label: string;
+  onClick: () => void;
+};
+
+export const MyNewButton: FC<MyNewButtonProps> = ({ label, onClick }) => (
+  <button onClick={onCLick}>{label}</button>
+);
+```
+
+**For stateful components:**
+
+```tsx
+export type MyNewButtonProps = {
+  label: string;
+  onClick: () => void;
+};
+
+export const MyNewButton: FC<MyNewButtonProps> = ({ label, onClick }) => {
+  // do something, then call the onClick fn. e.g.:
+  const handleClick = useCallback(() => {
+    alert(label);
+    onClick && onClick();
+  }, [label, onClick]);
+
+  return <button onClick={onCLick}>{label}</button>;
+};
+```
+
+### Rationale
+
+Since there's a lot of ways to create components, settling on one pattern helps maintain readability.
+But why _this_ style?
+
+See the discussion on the PR that introduced this pattern: [#2082](https://github.com/owncast/owncast/pull/2082).
+
+## Storybook
+
+We use [Storybook](https://storybook.js.org/) to create a component library where we can see and interact with each component.
+
+Make sure to include a `.stories.tsx` file with each (exported) component you create, and to update the stories file when making changes to existing components.
+
+You can run the Storybook server locally with `npm run storybook`.