@fuel-ui/react
v0.23.3
Published
<h1>⚡️ @fuel-ui/react</h1>
Downloads
1,671
Readme
🙋🏻 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
$ yarn add @fuel-ui/react$ pnpm install @fuel-ui/react👨🏻💻 Usage
First wrap your entire application using our ThemeProvider component
import { ThemeProvider } from '@fuel-ui/react';
const Main = () => (
<ThemeProvider>
<App />
</ThemeProvider>
);Then inside your app you can use as you want our component
import { Button, Form, Icon, Input, Stack } from '@fuel-ui/react';
const App = () => {
const [showing, setShowing] = useState(false);
function toggle() {
setShowing((s) => !s);
}
return (
<Stack css={{ maxW: '400px' }}>
<Form.Control isRequired>
<Form.Label htmlFor="email">Email</Form.Label>
<Input isFullWidth>
<Input.ElementLeft element={<Icon icon="Lock" />} />
<Input.Field
type={showing ? 'text' : 'password'}
name="password"
placeholder="Your password..."
/>
<Input.ElementRight>
<Button variant="outlined" onPress={toggle} css={{ mr: '-8px' }}>
Show
</Button>
</Input.ElementRight>
</Input>
<Form.HelperText>Try a strong password</Form.HelperText>
<Form.ErrorMessage>Password validation error</Form.ErrorMessage>
</Form.Control>
</Stack>
);
};💅🏻 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:
import { css } from '@fuel-ui/css';
import { Box } from '@fuel-ui/react';
const App = () => {
<Box className={customStyle()} css={{ display: 'flex' }}>
Hello world
</Box>;
};
const customStyle = css({
alignItems: 'center',
justifyContent: 'center',
bg: '$brand',
px: '$4',
textSize: 'base',
});💪🏻 Contributing
Besides our main Contribution Guide 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 to handle styling according to Stitches.
→ 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:
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<BoxProps>(
({ 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:
$ 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 package).
A base test of some component always include a11y test as first case:
import { testA11y } from '@fuels/jest';
import { MyComponent } from './MyComponent';
describe('MyComponent', () => {
it('a11y', async () => {
await testA11y(<MyComponent>Hello world</MyComponent>);
});
});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:
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 |
| 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 inside our components
→ @fuel-ui/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
This project utilizes Storybook for component development with some really cool addons 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
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
As icon set, we're using Tabler Icons here. Tabler Icons is a flexible icon family for interfaces, diagrams, presentations — whatever, really.
→ Radix Colors
We also use Radix Colors inside the @fuel-ui/css package. So, you we can check all colors inside the package folder.
→ XState
We also use XState as state management internally.
💪🏻 Contributing
Feel like contributing? That's awesome! We have a contributing guide to help guide you.
📜 License
The primary license for this repo is Apache 2.0, see LICENSE.