- [🙋🏻 Getting Started](#-getting-started)
- [📦 Install](#-install)
- [👨🏻💻 Usage](#-usage)
- [💅🏻 Styling Components](#-styling-components)
- [💪🏻 Contributing](#-contributing)
- [📖 Principles](#-principles)
- [🏭 Component Pattern](#-component-pattern)
- [🕹 Generating Components](#-generating-components)
- [✅ Testing Components](#-testing-components)
- [⚙️ Dev Environment](#️-dev-environment)
- [⌨️ Local Commands](#️-local-commands)
- [🛠 Tools](#-tools)
- [→ @fuel-ui/css](#-fuel-uicss)
- [→ StorybookJS](#-storybookjs)
- [→ RadixUI](#-radixui)
- [→ Radix Icons](#-radix-icons)
- [→ Radix Colors](#-radix-colors)
- [→ XState](#-xstate)
- [💪🏻 Contributing](#-contributing-1)
- [📜 License](#-license)
---
## 🙋🏻 Getting Started
Inside this package you'll found styled, very opiniated, acessible with high-quality user experience React components we're using inside as part of our design system inside our applications.
## 📦 Install
```bash
$ yarn add @fuel-ui/react
```
```bash
$ pnpm install @fuel-ui/react
```
### 👨🏻💻 Usage
First wrap your entire application using our `ThemeProvider` component
```jsx
import { ThemeProvider } from '@fuel-ui/react';
const Main = () => (
);
```
Then inside your app you can use as you want our component
```jsx
import { Button, Form, Icon, Input, Stack } from '@fuel-ui/react';
const App = () => {
const [showing, setShowing] = useState(false);
function toggle() {
setShowing((s) => !s);
}
return (
Email} />
Try a strong passwordPassword validation error
);
};
```
### 💅🏻 Styling Components
The best approach to style our component is by using `@fuel-ui/css` package. It's include all Stitches theme features and also our theme/tokens definitions.
You can simply create a `className` with it or use the `css` prop of our components:
```jsx
import { css } from '@fuel-ui/css';
import { Box } from '@fuel-ui/react';
const App = () => {
Hello world
;
};
const customStyle = css({
alignItems: 'center',
justifyContent: 'center',
bg: '$brand',
px: '$4',
textSize: 'base',
});
```
---
## 💪🏻 Contributing
Besides our main [Contribution Guide](../../CONTRIBUTING.md) it's very important you know about our code conventions and design principles if you want to contribute. Because of that we encourage you to read about all of these concepts and conventions bellow before start to develop or help here.
### 📖 Principles
→ **Simplicity:** Strive to keep the component API fairly simple and show real world scenarios of using the component.
→ **Composition:** Break down components into smaller parts with minimal props to keep complexity low, and compose them together. This will ensure that the styles and functionality are flexible and extensible.
→ **Accessibility:** When creating a component, keep accessibility top of mind. This includes keyboard navigation, focus management, color contrast, voice over, and the correct `aria-*` attributes.
→ **Dark Mode:** Make components dark mode compatible. Use our [darkTheme](../css/src/theme.ts) to handle styling [according to Stitches](https://stitches.dev/docs/theming#theme-specific-styles).
→ **Naming Props:** We all know naming is the hardest thing in this industry. Generally, ensure a prop name is indicative of what it does. Boolean props should be named using auxiliary verbs such as does, has, is and should. For example, `Button` uses `isDisabled`, `isLoading`, etc.
### 🏭 Component Pattern
There are two base props we have in all components: `as` and `css`. The `as` is very help if you want to change the base element of some component and the `css` prop will help you in order to change styles.
To make this available in some component inside our design system, we created a `_unstable_createComponent` function. This function will work together with the React's `createElement` function and the Stitches `styled` to create all behavior we need.
Check this example of our `Box` component:
```tsx
import { cx, styled } from '@fuel-ui/css';
import { createElement } from 'react';
import type { HTMLProps } from '../../utils';
import { _unstable_createComponent } from '../../utils';
export type BoxProps = HTMLProps['div'];
const Root = styled('div');
export const Box = _unstable_createComponent(
({ className, children, ...props }) => {
const classes = cx('fuel_Box', className);
return _unstable_createEl(Root, { ...props, className: classes }, children);
},
);
```
### 🕹 Generating Components
If you don't want to copy and paste or create some snippet, you can use simply our generator by running:
```bash
$ pnpm add:component --name NameOfYourComponent
```
### ✅ Testing Components
It's extremelly important that all components that has custom behaviors and settings are tested. So, we have `@fuels/jest` package that will help you to test using React Testing Library with some cool patches and modifications for accessibility tests as well (this package is a copy of ChakraUI [test utils](https://github.com/chakra-ui/chakra-ui/blob/next/tooling/test-utils) package).
A base test of some component always include `a11y` test as first case:
```jsx
import { testA11y } from '@fuels/jest';
import { MyComponent } from './MyComponent';
describe('MyComponent', () => {
it('a11y', async () => {
await testA11y(Hello world);
});
});
```
With test utils package you can run some triggers in order to test accessibility as well. Keyboard commands like `Tab` and `ArrowDown` is very easy by using `press` helper:
```jsx
import { press, render, screen } from '@fuels/jest';
import { RadioGroup } from './RadioGroup';
describe('RadioGroup', () => {
it('should focus correctly', async () => {
render(content);
await press.Tab();
expect(screen.getByLabelText('Default')).toHaveFocus();
await press.ArrowDown();
expect(screen.getByLabelText('Comfortable')).toHaveFocus();
await press.ArrowDown();
expect(screen.getByLabelText('Compact')).toHaveFocus();
});
});
```
---
## ⚙️ Dev Environment
This is the resources you'll need to know in order to run our dev environment.
### ⌨️ Local Commands
Use this commands in order to run locally and have our dev environment setup in your machine.
| Command | Description |
| -------------------- | ----------------------------------------------------------------- |
| `pnpm add:component` | Create a component based on our default [templates](./templates/) |
| `pnpm build:story` | Build Storybook project |
| `pnpm build` | Run tsup for build using ESbuild |
| `pnpm dev` | Run Storybook in development mode |
| `pnpm test` | Run Jest with json output file option for Storybook addon |
### 🛠 Tools
There are several tools we're using inside our design system and all of them is important,
mainly because we really care about our user experience and we wan't to [achieve good
accessibility](../../ACCESSIBILITY.md) inside our components
#### → [@fuel-ui/css](../css)
This is an internal package containing all styles, theme and tokens definitions that we need
for entire monorepo and mainly here in our design system. Couple tools like [Stitches]() and
[Radix Colors]() are used inside this package. We're encourage you to check it also.
#### → [StorybookJS](https://storybook.js.org/)
This project utilizes Storybook for component development with some [really cool addons](./.storybook/main.js) to help us to achieve accessibility, be able to cover user experience use cases in our and have a good documentation of each component.
#### → [RadixUI](https://www.radix-ui.com/)
We are using Radix as base components extensively here:
> Radix Primitives is a low-level UI component library with a focus on accessibility, customization and developer experience. You can use their components either as the base layer of your design system, or adopt them incrementally. We're
#### → [TablerIcons](https://tablericons.io/)
As icon set, we're using Tabler Icons here. Tabler Icons is a flexible icon family for interfaces, diagrams, presentations — whatever, really.
#### → [Radix Colors](https://www.radix-ui.com/colors)
We also use Radix Colors inside the `@fuel-ui/css` package. So, you we can check all colors inside the [package folder](../css/src).
#### → [XState](https://xstate.js.org/)
We also use XState as state management internally.
## 💪🏻 Contributing
Feel like contributing? That's awesome! We have a [contributing guide](../../CONTRIBUTING.md) to help guide you.
## 📜 License
The primary license for this repo is `Apache 2.0`, see [`LICENSE`](./LICENSE).