npm package: @postscript/components
Description: Postscript Component Library
Latest version: 20.3.9

# Postscript Component Library

## Storybook

The `main` branch is used to create a Storybook instance at [components.postscript.io](http://components.postscript.io), via [Chromatic](https://www.chromatic.com).

## NPM package usage

This repo generates an NPM package of components. Use components by importing them individually.

```
npm i @postscript/components
```

Note: If you are not seeing the latest version of this package, you may need to
run `@npm i @postscript/components@latest`.

```js
import { Button } from '@postscript/components';

const App = () => <Button>A Happy Button</Button>;
```

## Local repo usage

### CSS variables, reset, and design tokens

Import our base CSS once in your project.

```js
import '@postscript/components/dist/esm/main.css';
```

Import React Toastify CSS if needed.

```js
import 'react-toastify/dist/ReactToastify.css';
```

## Contributing

- [Jira project](https://postscript.atlassian.net/jira/software/c/projects/DES/boards/30)
- [Slack #front-end](https://postscript-workspace.slack.com/archives/CN99QFFP1)

### Testing changes in other repos

Currently, the easiest way to test changes from a feature branch in another repo is to publish a one-off, unique version of the package under a tag specific to you. [View instructions](https://www.notion.so/postscriptio/Publishing-a-feature-branch-package-to-test-in-other-Repos-e701eca0a3894df4a1763793fcf7d4e5)

### Versioning

Commits to `main` will publish a new `@postscript/components` package version. Use one of the following conventions when commiting/titling PRs to control semantic versioning.

- Major: your commit introduces any breaking change
  - add a `BREAKING CHANGE: ` prefix to the commit message (bumps the major version `X.#.#`)
  - e.g. changes to existing props, component refactors, module naming
- Minor: your commit adds new functionality in a backward compatible way
  - add a `feature: ` or `feat: ` prefix to your commit message (bumps the minor version `#.Y.#`)
  - e.g. add net new feature
- Patch: your commit changes something that already existed in a backward-compatible way
  - do not include either of the above in your commit message or description (bumps the patch version `#.#.Z`)
  - e.g. add/update minor styles, fix a bug, update a piece of documentation

Follow your commits to `postscript-frontend`, and address any changes needed to bump version.

### Pull requests

PRs require one engineer approval. If working with a designer, tag them as well. Directly requesting review from those with good knowledge of your changes is helpful if they're available.

Additionally, post for review in [#pull-requests](https://postscript-workspace.slack.com/archives/G016TN7RH44) and [#front-end](https://postscript-workspace.slack.com/archives/CN99QFFP1).

### How to add a new Icon

We utilize SVGR CLI to turn SVGs into React components. See `.svgrrc.js` for our
config.

1. Add SVG(s) to `src/icons/`
2. Run `npm run svgr`
3. Upon success, a summary will be logged
4. Add `import * as React from 'react';` to the new module(s)
5. Delete the original SVG file
6. Export the JSX component in `src/icons/index.ts`; `IconSet` uses this barrel
7. Run Storybook, and you should see the new component(s) in the `Icon` story examples automatically if everything has worked correctly

We utilize the following [automatic transformations](https://www.notion.so/postscriptio/Creating-New-Icons-bdc158ad30984e23a623617a12d1206b?pvs=4#a2f753595f22460e91460c620be71d0b).

### Creating components

Create your component with Typescript, its corresponding Storybook file, and a unit test file.

!! Be sure to add your new component to the exports list in `src/index.ts` and organize its display order in `.storybook/preview.js`

### Figma Code Connect Setup

[Code Connect](https://help.figma.com/hc/en-us/articles/23920389749655-Code-Connect) is the developer bridge from your component codebase to Figma. With Code Connect, bring your design system component code directly into Figma's Dev Mode. Preview example components that mirror the framework of your production code.

Code Connect uses [componentName].figma.tsx files to link code component properties with Figma component properties. Once the files are created and published, direct code output for the specified components will be visible in Figma's Dev Mode. [Learn More](https://help.figma.com/hc/en-us/articles/15023202277399-Use-code-snippets-in-Dev-Mode)

Once created, the files only need to be modified when component updates are made.

To enable Figma Code Connect integration:

You must have:
- [A Figma Dev mode seat](https://www.figma.com/dev-mode/)
- [A Figma access token](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens)

1. Install the Figma Code Connect CLI:
```bash
npm install --global @figma/code-connect@latest
```

2. In Figma, generate a personal access token in your account settings under the Security tab [(more info)](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens).

3. Create a new .env file:
```bash
touch .env
```
(Note: This file is listed in .gitignore and will not be listed as part of your commit.)

Then add the following to your .env file, along with your access token:
```
FIGMA_ACCESS_TOKEN="[your token here]"
```

4. Making update to a component:
   - Modify the appropriate `.figma.tsx` file next to your component
   - Run `npx figma connect publish` to publish the changes to Figma
   - Commit your changes and and publish as a PR to the components repo


5. Working with new components:
   - Create a `.figma.tsx` file alongside your component (e.g., `Button.figma.tsx` next to `Button.tsx`)
   - Import and use `figma.connect()` to link the component to your Figma design
   - Run `npx figma connect publish` to publish the changes to Figma

Example `.figma.tsx` file:
```tsx
import figma from '@figma/code-connect';
import React from 'react';
import MyComponent from './MyComponent';

const noop = () => {
  /* no-op */
};

figma.connect(MyComponent, 'https://www.figma.com/file/...', {
  props: {
    // Define component props that can be controlled in Figma
    size: figma.enum('Size', {
      Small: 'small',
      Medium: 'medium',
      Large: 'large',
    }),
    // Use noop for event handlers
    onClick: figma.boolean('Has Click', {
      true: noop,
      false: undefined,
    })
  }
});
```


For more details, see the [Figma Code Connect documentation](https://www.figma.com/code-connect-docs/api/config-file/).