From a3e77687d44a758ac23b9316fc70f53e205fc51f Mon Sep 17 00:00:00 2001 From: Gabe Kangas Date: Thu, 26 Jan 2023 15:23:17 -0800 Subject: [PATCH] Add select documentation to Storybook --- .../Design.stories.mdx | 64 +++++++++ .../Emoji.stories.mdx | 130 ++++++++++++++++++ .../ProductDefinition.stories.mdx | 91 ++++++++++++ .../WebComponents.stories.mdx | 78 +++++++++++ web/.storybook/tools/Document.stories.mdx | 5 + .../tools/generate-document-stories.mjs | 34 +++++ web/.storybook/tools/generate-stories.sh | 5 + 7 files changed, 407 insertions(+) create mode 100644 web/.storybook/stories-category-doc-pages/Design.stories.mdx create mode 100644 web/.storybook/stories-category-doc-pages/Emoji.stories.mdx create mode 100644 web/.storybook/stories-category-doc-pages/ProductDefinition.stories.mdx create mode 100644 web/.storybook/stories-category-doc-pages/WebComponents.stories.mdx create mode 100644 web/.storybook/tools/Document.stories.mdx create mode 100644 web/.storybook/tools/generate-document-stories.mjs diff --git a/web/.storybook/stories-category-doc-pages/Design.stories.mdx b/web/.storybook/stories-category-doc-pages/Design.stories.mdx new file mode 100644 index 000000000..ab1fad9bf --- /dev/null +++ b/web/.storybook/stories-category-doc-pages/Design.stories.mdx @@ -0,0 +1,64 @@ +import { Canvas, Meta, Story } from '@storybook/addon-docs'; + + + +# Owncast Design Guidelines & Resources + +A collection of design contribution guidelines and resources for the Owncast interface. + +> **All participating designers are highly encouraged to shape and evolve these guidelines!** +> It is a work in progress and as we have design contributors we can work to solidify the process, tools and resources. + +## 👋 Welcome + +Owncast is a is a live streaming and chat server targeted to anybody who has live streaming needs. This means anybody from corporate events, government meetings, game streamers, musicians, churches, TV stations, and more. + +Read the detailed [product definition](https://github.com/owncast/owncast/blob/develop/docs/product-definition.md) to learn more. + +## 🚢 How to contribute to product design + +1. Check out open [issues](https://github.com/owncast/owncast/issues) here on GitHub (we label them with `needs design`) +2. Feel free to open an issue on your own if you find something you would like to contribute to the project. +3. Add your contributions to an issue and we promise we will review your contribution carefully and foster discussions + +**We encourage you to:** + +- Get in touch with the team by joining our [Community Chat](https://owncast.rocket.chat). +- Check out our [Contributor Guide](https://owncast.online/help) and + [Code of Conduct](https://github.com/owncast/owncast/blob/develop/CODE_OF_CONDUCT.md) + +## 🎭 Target audience + +Owncast is a is a live streaming and chat server targeted to anybody who has live streaming needs. This means anything from corporate events, government meetings, game streams, concerts, TV stations, and more. + +## 💅 Design relevant materials + +Here is a list of design relevant information and materials: + +### Fonts + +http://owncast.online/components/?path=/story/owncast-style-guide-typography--page + +Body text: OpenSans + +Display/Header text: Poppins + +### Colors + +http://owncast.online/components/?path=/story/owncast-style-guide-default-theme--page + +### Design Files, Screenshots, etc + +We do not currently have any design files that fully represent the state of +the Owncast interface. However going forward it would be nice to resolve this +and collaborate on designs. + +We do have a [PenPot organization](https://design.penpot.app/#/dashboard/team/8373f780-f255-11ec-b774-f940e3befd53/projects). Please ask for access. + +## 🎓 License + +All design work is licensed under the +[MIT](https://mit-license.org/) + +[(Back to top)](#-table-of-contents) + diff --git a/web/.storybook/stories-category-doc-pages/Emoji.stories.mdx b/web/.storybook/stories-category-doc-pages/Emoji.stories.mdx new file mode 100644 index 000000000..f74d2cfd0 --- /dev/null +++ b/web/.storybook/stories-category-doc-pages/Emoji.stories.mdx @@ -0,0 +1,130 @@ + + +import { Canvas, Meta, Story } from '@storybook/addon-docs'; +import { Image, ImageRow } from './ImageAsset'; + + + +# Built-in Custom Emoji + + +## Blob + + LICENSE + + + + +## Conigliolo96 + + LICENSE + + + + +## Dog + + LICENSE + + + + +## Mutant + + LICENSE + + + + diff --git a/web/.storybook/stories-category-doc-pages/ProductDefinition.stories.mdx b/web/.storybook/stories-category-doc-pages/ProductDefinition.stories.mdx new file mode 100644 index 000000000..966646167 --- /dev/null +++ b/web/.storybook/stories-category-doc-pages/ProductDefinition.stories.mdx @@ -0,0 +1,91 @@ +import { Canvas, Meta, Story } from '@storybook/addon-docs'; + + + +# Owncast Product Definition + +## Why + +By defining the goals and target user bases we have something stable to guide decisions, features, conversations and keep clarity around what is being built. + +While these definitions and lists should not be seen as exhaustive, in theory, once this is seen as "complete" there should be few, if any changes, as that would note a large change in direction and goals. + +[TOC] + +## Vision + +> The out-of-the-box personal broadcast platform for DIY streamers and integrators. + +## Primary Goals + +- Useful out of the box. +- Fast to get running. +- Self-contained. +- An alternative, not a competitor. +- For individuals, not service providers. +- Easy to integrate into other projects/products. +- Low barrier to entry. +- Empowering. +- Customizable and hackable. + +## Primary Users + +### The DIY Streamer + +An individual who is streaming as a hobby, a project, or is moving their audience from an existing streaming platform. + +**Needs**: + +- Security/ownership of their own stream. +- Building an independent space. +- Personalization. +- Tools to manage a relationship with their audience. + +**Pains**: + +- Kicked off other streaming services. +- Feeling of inequality or bias. +- Their content has low visibility. +- Platform rules do not align with them. +- Do not agree with the forced ads, tracking and analytics. + +### The Integrator + +An individual or organization that has existing content, products or platforms that they want to add live streaming functionality to. + +**Needs**: + +- Broadcasting without censorship. +- Full ownership of their brand. +- Embedding and 3rd party playback. +- Support private or invite-only streams. +- Independence. + +**Pains**: + +- Censorship. +- Rules. +- Ads. +- Risk of losing viewers from competitors and distractions. + +**Desires**: + +- Hosting events. +- Running their own broadcasting service. + +## Secondary Users + +### The Viewer + +An audience member that is often, but not always, taking part in chat. + +**Needs**: + +- To watch high quality video. +- Ways to interact with the streamer. Chat, memes, emoji. +- Calls to actions, links, next steps. + +**Pains**: + +- Understanding the interface and knowing they're in the correct place. + diff --git a/web/.storybook/stories-category-doc-pages/WebComponents.stories.mdx b/web/.storybook/stories-category-doc-pages/WebComponents.stories.mdx new file mode 100644 index 000000000..85294c265 --- /dev/null +++ b/web/.storybook/stories-category-doc-pages/WebComponents.stories.mdx @@ -0,0 +1,78 @@ +import { Canvas, Meta, Story } from '@storybook/addon-docs'; + + + +# 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 `. + +## 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 = ({ label, onClick }) => ( + +); +``` + +**For stateful components:** + +```tsx +export type MyNewButtonProps = { + label: string; + onClick: () => void; +}; + +export const MyNewButton: FC = ({ label, onClick }) => { + // do something, then call the onClick fn. e.g.: + const handleClick = useCallback(() => { + alert(label); + onClick && onClick(); + }, [label, onClick]); + + return ; +}; +``` + +### 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`. + diff --git a/web/.storybook/tools/Document.stories.mdx b/web/.storybook/tools/Document.stories.mdx new file mode 100644 index 000000000..4b44102b5 --- /dev/null +++ b/web/.storybook/tools/Document.stories.mdx @@ -0,0 +1,5 @@ +import { Canvas, Meta, Story } from '@storybook/addon-docs'; + + + +{{content}} diff --git a/web/.storybook/tools/generate-document-stories.mjs b/web/.storybook/tools/generate-document-stories.mjs new file mode 100644 index 000000000..0c565a7cd --- /dev/null +++ b/web/.storybook/tools/generate-document-stories.mjs @@ -0,0 +1,34 @@ +import fs from 'fs'; +import handlebars from 'handlebars'; + +const template = fs.readFileSync('./Document.stories.mdx', 'utf8'); +let t = handlebars.compile(template, { noEscape: true }); + +const documents = [ + { + title: 'Product Definition', + name: 'ProductDefinition', + path: '../../../docs/product-definition.md', + }, + { title: 'Design', name: 'Design', path: '../../../.design/DESIGN.md' }, + { + title: 'Building Frontend Components', + name: 'WebComponents', + path: '../../../web/components/_COMPONENT_HOW_TO.md', + }, + { + title: 'Get Started with Owncast Development', + name: 'Development', + path: '/tmp/development.md', + }, +]; + +documents.forEach(doc => { + if (!fs.existsSync(doc.path)) { + return; + } + + const document = fs.readFileSync(doc.path, 'utf8'); + const output = t({ name: doc.name, title: doc.title, content: document }); + fs.writeFileSync(`../stories-category-doc-pages/${doc.name}.stories.mdx`, output); +}); diff --git a/web/.storybook/tools/generate-stories.sh b/web/.storybook/tools/generate-stories.sh index fc9bcbfad..48798cda1 100755 --- a/web/.storybook/tools/generate-stories.sh +++ b/web/.storybook/tools/generate-stories.sh @@ -2,3 +2,8 @@ # Generate the custom Emoji story node generate-emoji-story.mjs >../stories-category-doc-pages/Emoji.stories.mdx + +# Generate stories out of documentation + +# Pull down the doc about development +curl -s https://raw.githubusercontent.com/owncast/owncast.github.io/master/content/development.md >/tmp/development.md