
Library name:       fuegokit/react
Version:            3.7.11
Repository URL:     
License:            MIT
License Text:       # Fuegokit React

A React implementation of Appfire's design system.

[Read the docs here.](https://fuegokit.design/react)

[View the deployed Storybook here.](https://fuegokit.design/react-storybook)

## Getting Started

Use the package manager of your choice to install Fuegokit in your application.

```bash
npm install @fuegokit/react

// or

yarn install @fuegokit/react
```

Then import the component in your application:

```javascript
// using ES Module 'import' syntax
import {Box, Heading, Text, useTheme, ThemeProvider} from 'fuegokit'
```

```javascript
// using CommonJS 'require' syntax
const {Box, Heading, Text, useTheme, ThemeProvider} = require('fuegokit')
```

(Note: if your application isn't using a bundler that supports ES Module tree-shaking out of the box, see the note on [Minimizing bundle size](#minimizing-bundle-size) below.

## npm token

`@fuegokit/react` is published to `npm` using Appfire's internal registry, which means you'll need to add an an npm token in order to install it.

[Read our npm guide here.](https://appfireteam.atlassian.net/wiki/spaces/experience/pages/95441944614/How+to+install+our+npm+packages).

[If you run into trouble, reach out in Slack](https://appfireworkspace.slack.com/archives/C03CTJZ4BUH) and we'll get you what you need to get up and running.

## Project structure

Installable React components are exported from `index.ts` at the root of the project.

This project ships with a Storybook installation, and the project's `*/.stories.tsx` files are located in the `stories` folder.

Here's the current structure:

```
.
├── CHANGELOG.md
├── README.md
├── babel.config.js
├── bitbucket-pipelines.yml
├── contributor-docs
│   ├── CONTRIBUTING.md
│   ├── PlainDocsExample.stories.mdx
│   └── adrs
│       └── adr-001-file-structure.md
├── jest.config.js
├── package-lock.json
├── package.json
├── rollup.config.js
├── src
│   ├── components
│   │   ├── BaseStyles.tsx
│   │   ├── Box
│   │   ├── Fuegoicon
│   │   ├── Heading
│   │   ├── InlineDialog
│   │   ├── MaxWidthWrapper
│   │   ├── PageSizes
│   │   ├── Pattern
│   │   ├── Spacer
│   │   ├── Text
│   │   ├── ThemeProvider
│   │   └── VisuallyHidden
│   ├── constants.ts
│   ├── index.ts             // exports all components
│   ├── stories
│   │   ├── Behaviors
│   │   ├── BuildingBlocks
│   │   ├── Docs
│   │   ├── Helper
│   │   ├── Patterns
│   │   └── System
│   ├── sx.ts
│   ├── theme.ts
│   └── utils
│       ├── test-helpers.tsx
│       ├── test-matchers.tsx
│       ├── testing.tsx
│       ├── theme-get.js
│       ├── theme-preval.js
│       ├── theme-utils.js
│       └── types
└── tsconfig.json
```

Our file structure conventions are documented in an [ADR template](/contributor-docs/adrs/adr-001-file-structure.md).
The [proposal](/contributor-docs/adrs/adr-001-file-structure.md) suggests migrating this repo to the following structure:

```
fuegokit-react/
├── src
│   ├── Fuegoicon
│   │   ├── index.ts
│   │   ├── Fuegoicon.tsx           // primary component
│   │   ├── icon.helpers.tsx        // helper functions, lib, utils, etc
│   │   ├── Fuegoicon.stories.tsx   // stories
│   │   ├── Fuegoicon.test.tsx      // tests
│   │   ├── Fuegoicon.mdx           // docs (components will be documented in MDX, so not .md files but .mdx files)
│   │   ├── Fuegoicon.yml           // component metadata (for future use with GraphQL in docs framework, to track deprecation and lifecycle status, etc)

```

If you're interested in taking that on, there's [a ticket for that work here](https://bobswift.atlassian.net/browse/DS-177?atlOrigin=eyJpIjoiYjY4OGU3YTlmOTVlNDU1Nzg2OTI2NTZkNTcwZjY5ZDEiLCJwIjoiaiJ9).

We would love it if you felt like taking that on! Feel free to grab that task and open a Pull Request.

## Documentation

View the docs at [https://fuegokit.design/react](https://fuegokit.design/react).

Right now, the [deployed Storybook](https://fuegokit.design/react-storybook) should serve as introductory docs to using this implementation.

## Installation

Install Fuegokit in your project with the package manager of choice

```sh
npm install @fuegokit/react

// or

yarn add @fuegokit/react
```

You can now import Fuegokit from the main package module:

```javascript
// using ES Module 'import' syntax
import {Box, Heading, Text, useTheme, ThemeProvider} from '@fuegokit/react'
```

```javascript
// using CommonJS 'require' syntax
const {Box, Heading, Text, useTheme, ThemeProvider} = require('@fuegokit/react')
```

## Roadmap

You can track our roadmap progress in the [Roadmap](https://appfireteam.atlassian.net/wiki/spaces/experience/pages/95847874604/Iteration+Plan+for+Jan+18+-+April+21+2023), follow along for more detail in the Design Systems [Confluence Space](https://appfireteam.atlassian.net/wiki/spaces/CBW/pages/92813721685/Appfire+Design+Systems), or connect with us in the [#design-systems Slack channel](https://appfireworkspace.slack.com/archives/C03CTJZ4BUH).

## Contribution

We welcome contributions, whether it's a comment, bug report, or PR!

> 👉 See [`CONTRIBUTING.md`](/contributor-docs/CONTRIBUTING.md) the Contribution docs for more info on code style, testing, coverage, and troublshooting. Whether it's a bug report, a new component proposal, or something as simple as a grammatical change to our documentation, our best work comes from collaborating directly with the teams using Fuegokit in their projects.

If you're a Product Manager, designer, or a developer and you'd like to start a new component proposal, the easiest and fastest way to get the process kicked off is:

1. Copy the [component proposal template here](https://appfireteam.atlassian.net/l/c/ranCtZ8H).
2. Paste the New Component Proposal template into a New Issue, with the "Create Issue in Epic" button on the [Fuegokit React project in Jira](https://bobswift.atlassian.net/browse/DS-108).
3. Fill out the template as best you can, and the systems team will get in touch directly to discuss next steps. [Our process guide talks through the process](https://appfireteam.atlassian.net/wiki/spaces/experience/pages/95430639629/How+to+work+with+the+Design+Systems+team+at+Appfire). Generally, we want to build it.

### Visual testing with Storybook

Fuegokit ships with [Storybook](https://storybook.js.org/docs/react/configure/typescript) to allow developers and designers to experience the behavior of Fuegokit components in the browser.

A deployed instance of Storybook is available at [at this link](https://fuegokit.design/react-storybook).

If you're building stories for your component with Storybook, you'll find all of the stories in the `src/stories` folder.

Importing the `<ThemeProvider>` component as well as the `<BaseStyles>` component in your stories is a requirement. This is aimed at ensuring that our users get a consistent experience.

```typescript
import React from 'react'
import BaseStyles from '../../components/BaseStyles'
import {ThemeProvider} from '../..'

import YourComponent from '../../components/YourComponent'
import {InlineDialogSizesProps} from '../../components/YourComponent'

export default {
  title: 'Category/Your Component',
  component: YourComponent,
  decorators: [
    Story => {
      // Since portal roots are registered globally, we need this line so that each storybook
      // story works in isolation.
      return (
        <ThemeProvider>
          <BaseStyles>
            // use {Story()} instead of <Story /> in order for displayNames to render properly
            {Story()}
          </BaseStyles>
        </ThemeProvider>
      )
    }
  ],
  argTypes: {}
} as Meta

export const yourComponent = (args: yourComponentProps) => {
  return <YourComponent {...args} />
}

yourComponent.args = {
  yourSizeProp: 'small'
}
```

To run storybook locally:

```sh
yarn storybook

```

You can then navigate to `http://localhost:6006/`.

If you run into issues with Storybook or have a question, reach out in the #design-systems Slack channel and we'll get back to you directly. For more on configuring your environment to support building Storybook stories in Typescript, please consult the [Storybook docs](https://storybook.js.org/docs/react/configure/typescript).

### Peer dependencies

Fuegokit ships with a few libraries labeled as peer dependencies. These are libraries we've separated because they're commonly installed in the host project, and having multiple versions can introduce errors.

Fuegokit requires the following libraries to be installed along with it:

- `styled-components` at version 4.0.0 or higher
- `react` at versions 16.8.0 or higher
- `react-dom` at versions 16.8.0 or higher

### Working with bundlers

Fuegokit React does not transform code to support older ECMAScript versions, like ES5.

`@fuegokit/react` uses features like `Object.assign` as well as some newer syntax features like Object destructuring, spreading, and the nullish coalescing operator.

Environments that Fuegokit React is used in should have all the necessary polyfills to comply with the latest code standards,
since we don't ship with those.

In cases where it may be necessary for your projects to transform this code to support for older browsers, we provide a number of boilerplate projects that demonstrate backwards-compatibility in different configurations with various bundlers.

#### With Parcel

If your project is using Parcel as transpiler - you'll need:

- `@babel/core` at versions 7.17.10 or higher
- `babel-preset-env` at versions 1.7.1 or higher
- `babel-preset-react` at versions 6.24.1 or higher
- `babel-plugin-styled-components` at versions 2.0.7 or higher
- plus a `.babelrc` file with context `{ "presets": ["env", "react"] }`

[See an example boilerplate repository of a Parcel project with @fuegokit/react here.](https://bitbucket.org/appfire/fuegokit-example-parcel-yarn-workspaces-react/src/main/)

#### With Webpack 4

Additional configuration guidelines coming soon.

#### With Webpack 5

If your project is using Webpack 5 as a bundler - you'll need:

- `@babel/core` at versions 7.17.10 or higher
- `@babel/preset-env` at versions 7.16.11 or higher
- `@babel/preset-react` at versions 7.16.7 or higher
- a `.babelrc` file with context `{ "presets": ["@babel/preset-env", "@babel/preset-react"] }`

[See an example boilerplate of a Webpack 5 project with @fuegokit/react here.](https://bitbucket.org/appfire/fuegokit-example-webpack-5-babel-7-react-17/src/main/)

### Building in the Atlassian ecosystem

A note about working with Atlaskit, extending Atlaskit types, and the right approach.

Our products' host environment – the Atlassian product ecosystem – has provided its own design systems and made various tools available over the years.

This can lead to some ambiguity about what we should or shouldn’t build. It has also quite possibly (and counterintuitively) led to increased code and design debt, which our goal is to reduce.

Fuegokit React balances YAGNI with the needs of the people it is meant to support, but generally, we do not design our components to wrap Atlassian's React components. If your design requires an Atlassian component, consider a `children`-based API.

### Polyfills, Browser Support, & Progressive Enhancement

It's important for us to build a usable experience for everyone, regardless of browser choice. As a guiding principle, users on older browsers should be able to use your feature. The good news is that all modern browsers (Chrome, Firefox, Edge, Safari, and mobile browsers like Samsung Internet and UC Browser) support both flexbox and CSS grid, and you can use those features safely and without reservation. If your application needs to support Internet Explorer, [this resource](https://css-tricks.com/css-grid-in-ie-debunking-common-ie-grid-misconceptions/) explains how certain CSS grid features work a bit differently.

Fuegokit supports the current versions of [Chrome](https://www.google.com/chrome), [Firefox](http://mozilla.org/firefox), [Safari](http://www.apple.com/safari), and [Microsoft Edge](https://www.microsoft.com/en-us/windows/microsoft-edge), as well as the [Firefox Extended Support Release](https://www.mozilla.org/en-US/firefox/organizations/). This is in line with [link to Appfire's supported browser page here](#).

If your application's UI feature requires using an [experimental CSS feature](https://drafts.csswg.org) like the the `:has()` relational pseudo-class or `subgrid`, reconsider the feature so that the widest possible number of users can use it.

When building and designing user experiences for Appfire products, use progressive enhancement -- start with a baseline experience that works for everybody, and enhance it to be a better experience for users on modern browsers. You can use the `@supports` [feature query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Conditional_Rules/Using_Feature_Queries) to detect support, which can come in handy for more newer parts of the specification for commonly used CSS features like `gap` with both `flexbox` and `grid`.

If you're wondering when and where to incorporate a CSS feature, the design systems team is here to help; if you have a question, reach out in Slack the [`#design-systems`](https://appfireworkspace.slack.com/archives/C03CTJZ4BUH) channel.

### Minimizing bundle size

Module bundlers that use ECMAScript modules ("ESM" or "ES Modules" are also used interchangeably) will automatically tree-shake Fuegokit, which means that no unused code should be included in your final bundle.

However, if your application doesn't use ESM, you may still be able to drastically reduce the size of your final bundle by importing components directly from the `lib` subfolder:

```javascript
// using ES Module 'import' syntax
import {Box, Heading, Text, useTheme, ThemeProvider} from '@fuegokit/react'
```

```javascript
// using CommonJS 'require' syntax
const {Box, Heading, Text, useTheme, ThemeProvider} = require('@fuegokit/react')
```

Note: the modules in the `lib` folder are CommonJS-style modules -- if you're using ESM and a compatible module bundler, taking this approach and importing files individually from the `lib` folder isn't providing any benefit to you.

### Typescript

Fuegokit includes TypeScript support and ships with its own typings. You'll still need to install type definitions for the peer dependencies if you import those in your own application.

Once you've installed Fuegokit, you can import components and their prop interfaces from the `@fuegokit/react` package:

```typescript
import {Box, BoxProps} from '@fuegokit/react'
```

### Silencing browser warnings

Just like any application, Fuegokit emits some browser warnings to the JavaScript console under certain conditions, for example, when a component or a prop may be deprecated. You can silence these warnings by setting the `NODE_ENV` variable to `production` during bundling.

## Reporting bugs

Bugs and unexpected behaviors are part of life, and if you encounter a bug, please follow these steps:

1. Use [this bug report template](https://appfireteam.atlassian.net/l/c/dCyeTFtn)
2. Create a new issue on the [`@fuegokit/react` Jira epic](https://bobswift.atlassian.net/browse/DS-108) using the "New Issue" feature in Jira, and choose "Bug".
3. Fill out the template and include screenshots and as much context as you can. A member of the systems team will reach out follow up with next steps.

WIP
WIP
