@test-changesets/react v0.0.1
🙋🏻 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 @test-changesets/react
$ pnpm install @test-changesets/react
👨🏻💻 Usage
First wrap your entire application using our ThemeProvider
component
import { ThemeProvider } from "@test-changesets/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 "@test-changesets/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="LockClosedIcon" />} />
<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 @test-changesets/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 "@test-changesets/css";
import { Box } from "@test-changesets/react";
const App = () => {
<Box className={customStyle()} css={{ display: "flex" }}>
Hello world
</Box>;
};
const customStyle = css({
alignItems: "center",
justifyContent: "center",
bg: "$accent9",
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 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 "@test-changesets/css";
import { createElement } from "react";
import type { HTMLProps } from "../../utils";
import { createComponent } from "../../utils";
export type BoxProps = HTMLProps["div"];
const Root = styled("div");
export const Box = createComponent<BoxProps>(
({ className, children, ...props }) => {
const classes = cx("fuel_box", className);
return createElement(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 testes. So, we have @test-changesets/test-utils
package that will help you to test using React Testing Library with some cools 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 "@test-changesets/test-utils";
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 "@test-changesets/test-utils";
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
→ @test-changesets/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
→ Radix Icons
As icon set, we're using Radix Icons here. Radix Icons is crisp set of 15×15 icons designed by the Modulz team.
→ Radix Colors
We also use Radix Colors inside the @test-changesets/css
package. So, you we can check all colors inside the package folder.
→ Jotai
We also use Jotai as state management internally mainly for provider's like components.
Jotai takes a bottom-up approach to React state management with an atomic model inspired by Recoil. One can build state by combining atoms and renders are optimized based on atom dependency. This solves the extra re-render issue of React context and eliminates the need for the memoization technique.
💪🏻 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
.
2 years ago
2 years ago