@podiumhq/podium-ui NPM

Podium UI

A library of Podium UI components built in React to be used in our applications.

See all the components here: https://storybook.podium.com (going to change url soon)

Adding `podium-ui` to a Library to be used within another app

Do this when creating a library to be used in multiple front-end apps (aka: wheres-my-money, podium-oauth-modal, podium-app-banner).

1. add `podium-ui` as a peer dependency to the project. It's very important that it's a peer dependency or else it'll duplicate itself in the bundle.

# in ~/code/your-library
yarn remove podium-ui # If git version is installed
yarn add --peer @podiumhq/podium-ui
yarn add --dev @podiumhq/podium-ui # so you dev on it in Storybook or whatever you use.

# Or using npm
npm uninstall podium-ui # If git version is installed
npm install --peer @podiumhq/podium-ui
npm install --save-dev @podiumhq/podium-ui # so you dev on it in Storybook or whatever you use.

This will install the newest version and pin the major version.

2. Next add podium-ui to the other app, as a normal dependency along with your library

# in ~/code/existing-app

yarn add @podiumhq/podium-ui
yarn add styled-components
yarn add @podiumhq/<YOUR LIBRARY GOES HERE>

# Or using npm...
npm install --save @podiumhq/podium-ui
npm install --save styled-components # Podium-ui uses this as a peer-dependency
npm install --save @podiumhq/<YOUR LIBRARY GOES HERE>

Adding `podium-ui` to a New App

⚠️ All new apps should be built within kazaam if they are part of the main Podium interface (do they have a link in the nav bar)

But if creating an app outside of kazaam add podium-ui as a dependency to the project like the following:

# in ~/code/new-app

yarn remove podium-ui
yarn add @podiumhq/podium-ui
yarn add styled-components

# Or using npm...
npm uninstall podium-ui # If git version is installed
npm install --save @podiumhq/podium-ui
npm install --save styled-components # Podium-ui uses this as a peer-dependency

Include components like normal:

import { Button } from '@podiumhq/podium-ui';

With Styled Components

To import global CSS using styled components do the following:

  import { GlobalStyles } from '@podiumhq/podium-ui';

  ...

  <Root>
    <GlobalStyles />
    <App>
      ...
    </App>
  </Root>

To use Podium specific colors:

import { colors } from '@podiumhq/podium-ui';

export const StyledText = styled.div`
  color: ${colors.jumbo};
`;

Development

Testing

Please Look at our Testing Documentation for more info.

Developing in Storybook

Podium UI uses Storybook, which allows you to see and test all the components via a web interface.

Using Yarn:

yarn
yarn storybook

Testing Changes Locally in another App

⚠️ Don't try to use npm link! It generally doesn't work with our build.

Instead use

bin/publish-branch

that will push up a git tag based on your branch name. Running this command will print in your terminal directions on how to import it in the other project.

You can run this as many times as you want to keep on trying it.

Publishing & Versioning

Before you create your PR, bump the version number appropriately in package.json, commit, and push. Once the PR is merged it will be published to Podium's NPM repository automatically.

9.2.3
| | |
| | +- PATCH: Refactored internally, no component's props were changed or added.
| |           No CSS was added or modified.
| |
| +--- MINOR: Added a new component or added props to an existing component.
|             No CSS layout or sizing was changed! Colors are OK as long as they
|             still look ok on the same color background (dark v.s. light).
|
+----- MAJOR: Changed or deleted a component's props, added proptypes that weren't there before.
              NOTE: resizing an existing component counts as a breaking change!

I know it may seem like this is a bit strict and will result in a lot of Major changes, and that's OK. It's better to know if it's safe to update Podium-UI then to have low amounts of Major changes. Also there's ways to make things backwards compatible, like make a new component rather than a modifying an existing one.

Old Builds

If you have an older version of Webpack / Babel it might be needed to use the legacy-build

Click below to expand these suggestions.

Styles

Mostly we Don't Use SASS/SCSS anymore, however if you're in this situation just click on the line below to expand the instructions:

Included are a few stylesheets with variables to help us keep a consistent design. You can include them in your scss like so:

@import '~@podiumhq/podium-ui/src/styles/colors';

.podium-green-text {
  color: $podium-brand;
}

It is recommended to include the base stylesheet in the global or base stylesheet of your app. base.scss includes sanitize.css, the AvenirNext font family, and a few other basic styles.

If you'd rather not include the entirety of the AvenirNext font family, you can instead just include global.scss. Be aware that at this point you will also have to manually include sanitize.scss.

It should be noted that the use of scss and css modules is deprecated in Podium UI. The base.scss and global.scss stylesheets can still be used as noted above.

There are equivalent JavaScript files that will set global styles using styled components. Where you import from will depend on what module system your project uses. If using native modules, you can import the base and global from podium-ui/build/styles to globally set styles.

// Includes sanitize.css and AvenirNext font family
import '@podiumhq/podium-ui/build/styles/base';

// Doesn't include sanitize and AvenirNext font family
import '@podiumhq/podium-ui/build/styles/global';

If using another module system, such as CommonJS, UMD, AMD, etc., then you can import or require from the podium-ui/legacy-build/styles;

// Includes sanitize.css and AvenirNext font family
import '@podiumhq/podium-ui/legacy-build/styles/base'; // or
require('@podiumhq/podium-ui/legacy-build/styles/base');

// Doesn't include sanitize and AvenirNext font family
import '@podiumhq/podium-ui/legacy-build/styles/global'; // or
require('@podiumhq/podium-ui/legacy-build/styles/global');

Old JavaScript Bundles

The build process currently makes two builds, one into a build directory and another into a legacy-build directory. Both are transpiled with Babel from ES6+ into valid JavaScript. However, the build directory contains a build that uses native JavaScript modules with import and export. This gives the benefit of tree shaking with Webpack 2. The legacy-build converts native modules into CommonJS modules. The package.json has the main field pointing to legacy-build and the module field pointing to build. If your project is using native modules, it should point to the module field as the entry point and give you tree shaking benefits. Otherwise, it should default to the main field and work as usual.