Scallywag UI

React components and hooks to build interfaces at Pirate 🏴‍☠️

Usage

To use Scallywag in your project, add it as a dependency:

$ yarn add scallywag-ui

To get started, you must wrap the root of your React App with the UIProvider component with the required theme like so:

import { UIProvider } from "scallywag-ui";

const App = ({ children }) => <UIProvider theme="pirate">{children}</UIProvider>;

Import the components into your file as required like so:

import { Button, FlexibleContainer } from "scallywag-ui";

const MyComponent = () => (
  <FlexibleContainer padding="md">
    <Button label="Hello" onClick={() => alert("ohhai")} />
  </FlexibleContainer>
);

Contributing

Getting started locally

• Install Node and Yarn
• Run yarn to install dependencies
• Run yarn start to start the project in development/watch mode. Everything will be rebuilt upon making changes. This is handy when you don't need to use Storybook, and perhaps testing locally using other methods like yarn link.
• Run yarn storybook to use Storybook locally when building components.
• Run yarn build to create a production build in the dist folder.
• Run yarn test or yarn test:watch to run tests.
• Optional: If using VS Code, install the following extensions to make your life easier:
  • ESLint
  • vs-code-styled-components
  • Prettier

Creating a new component

• Run yarn component to create a new component that follows the same opinionated structure for consistency and ease of export, with a types, styling, component and story file as well as an index.tsx for exporting the components.
• To ensure your component is bundled and available in the package, you must export it in the src/index.ts file.

Writing tests

• Ideally, tests should be written for all components/utils. Even for cases where it might seem unneccesary, writing a test will help guard against changes to a component's API to avoid any breaking changes making their way into the package by accident.
• Tests are set up with Jest as the test runner and React Testing Library as the assertion library

Tests can be set up as follows:

• A test will be set up as part of the component bootstrapping step when running yarn component
• Setup your test component in the provided renderWithProviders invocation
• Write your assertions

As a rule, when writing tests, you should:

• Avoid testing implementation details (for example, prefer testing the resultant UI of a component rather than React state)
• Prefer writing longer tests that reflect the actual use of a component, rather than making isolated assertions. Try picking out a typical user flow and make assertions in sequence.

Project structure

The library is bootstrapped with TSDX, which gives us a minimal configuration setup for things like Typescript, ESLint, Prettier, Jest and Rollup. TSDX supplies two environments, one for development and one for production. This lets us reliably use libraries like invariant to provide rich error messages while developing locally, and safely being tree-shaken out of production builds.

Workflow

Git flow

• Branch off master, referencing an issue or jira ticket where relevant.
• Do work.
• Where relevant, your commit messages should be formatted in the Conventional Commit format. This allows us to generate a Changelog for each release. To make this step easier, you can run yarn cz-commit to make your commit message. You needn't do this for every commit, but it's useful to make one formatted commit message per feature so that it gets included in the changelog.
• Gain approval and merge your branch into master.

Testing the package in another project

It's sometimes useful to test components in the context that they might be used. If the Storybook environment doesn't sufficiently cover your use case you can use yarn link to test your changes inside another project.

• Inside your local Scallywag directory, run yarn link, then yarn start to watch for changes
• Inside the project you want to test Scallywag in, for example Jetsam, run yarn link scallywag-ui, then start the project locally

This will override the version of Scallywag being used in the project by creating a symlink to your local version.

If you'd like to run the new version alongside the existing one you can change the Scallywag name in package.json before running yarn link.

For example:

• "name": "scallywag-ui-next" inside package.json
• yarn link inside Scallywag directory
• yarn link scallywag-ui-next inside test project

Now you'll have access to both scallywag-ui and scallywag-ui-next in your project.

Links can be removed by using yarn unlink in place of yarn link. When unlinking scallywag in a project you will need to run yarn install --check-files to re-install the actual scallywag package. See here.

Notes ⚠️ : Locally our dev dependencies will be included inside node_modules. This means that libraries like React could be included twice in the project you're using to test Scallywag, causing errors when using features like hooks. To prevent this happening you can use aliases in your project to make sure these libraries are always imported from the top level node_modules

Resources:

• yarn link https://classic.yarnpkg.com/en/docs/cli/link/

Releasing a new version

• Ensure master is up to date and any feature branches you wish to be included in the release are merged.
• Run yarn release. This runs standard-version, a package which updates the CHANGELOG.md and bumps the package version based on the recent changes' commit messages. This command will also commit the new changelog and package.json files and tag the branch for you.
  • This will also run git push && git push --tags. The new tag on the master branch will trigger Circle CI to build and publish the package to npm.
  • It will then run yarn deploy which will deploy the storybook-static folder to gh-pages - https://piratestudios.github.io/scallywag-ui
• Update the package version where it is used by running yarn upgrade scallywag-ui.
• From the created tag, click "Create release from tag" and update with any extra info

Figma Design Handoff

In order to keep the work that the designers do in line with the theme values we have available in Scallywag, there are a few Figma utilities available inside the figma folder. You can use these as follows:

• generateFigmaStyles.js parses our Styled Components theme into a shape recognised by the Figma Theme UI plugin. With this plugin, all text styles need to share a key, which is currently based on the relative line height values. If the theme shape needs to be updated, you must match the object based on the shape described here. This file can be imported into Figma using the Theme UI plugin and the text and colour styles will then become available in the figma doc. This script can be executed using yarn figma:generate-theme
• scallywag-figmatheme.js is the output file from the above script. Currently, this will get recompiled automatically during a scallywag build.
• scallywag-template.fig is a prepopulated template document that can be handed to the design team and imported into Figma and used as a base template for designs. This should be updated and redistributed when a change is made to the theme.
• FigmaRemoveStylesPlugin is a simple plugin that allows you to remove all the associated styles on a Figma document. This can be used when updating the scallywag-template.fig document to quickly remove all the existing styles and import the new ones. This can be added as a local development plugin with the steps described here but instead of creating a new plugin, selecting the manifest.json file that exists in the plugin folder. Once added, you will need to run the local plugin with the following command: yarn figma:remove-styles-plugin