@fuel-ui/react v0.23.2

• 🙋🏻  Getting Started
• 📦  Install
  • 👨🏻‍💻  Usage
  • 💅🏻  Styling Components
• 💪🏻  Contributing
  • 📖  Principles
  • 🏭  Component Pattern
  • 🕹  Generating Components
  • ✅  Testing Components
• ⚙️  Dev Environment
  • ⌨️  Local Commands
  • 🛠  Tools
    • → @fuel-ui/css
    • → StorybookJS
    • → RadixUI
    • → Radix Icons
    • → Radix Colors
    • → XState
• 💪🏻  Contributing
• 📜  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

$ 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.

🛠  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.