CityBase Components

This library contains CityBase React components for use across all current and future CB applications (NFE, RMD, Kiosk, POS).

• Development setup

• Component styles

• Storybook

  • Storybook addons
  • Storybook deployment

• Adding new components

• Version bumping and publishing

  • Version bumping
  • Publishing new versions to NPM

• Consuming in your application

  • Adding to existing application
  • Local import and development
  • Importing and using components

Development setup

• Install Node.js with asdf by running asdf install
• brew install yarn && yarn

The following statement will inheritly be called with yarn, but you can run it with this command to not try to fetch new dependencies

• yarn run build

Component styles

• All component molecules and atoms are constructed from the layout primitive atoms (Box, Cover, Stack, etc...). For most atoms and molecules, styling is handled via passing props to the layout atoms. Layout atoms have their own .styled.js files where props are incorporated into standard styled-components styling.

• When creating new atoms/molecules, please make sure to use the layout primtiives to construct your component and follow the styling practices of already existing atoms/molecules

• All components are also themed via integration with Frontend Configuration Service. Components have a .theme.js file within their directory which specifies what style properties of the component are available to be themed and which provides fallback default values. These default values will be used if no override is specified in the theme.json file that comes back from FCS, or if the theme.json file is missing due to a request failure.

• When creating new components, please follow the theme conventions of existing atoms and molecules. Hardcoding style properties is acceptable if those style properties will not change from client to client. (E.g., the ButtonWithAction atom hardcodes its border radius to a value of "2px", while properties such as background color are themeable values specified in the .theme.js file.

• Both atoms and molecules can make use of the "variants" ability to specify different types of components. For example, the ButtonWithAction component comes with "primary," "secondary," and "danger" variants, among others. When using a component within an application, the specific variant is specified by passing the string name as the value of the variant prop.

Storybook

This repo uses React Storybook v8 for interactive component display.

Please include new component stories as this library will also be a sandbox.

• yarn storybook
• open browser to localhost:9001

Storybook addons

The repo uses all of the standard addons that come with Storybook v8, including the box model visualizer, measuring tool, and themes. The themes are currently static themes derived from FCS output. For the time being, when changes are made to themes in FCS, those changes need to be replicated inside of the .storybook/themes/ directory in order for component stories to pick up on them. Ideally in the future a script will dynamically pull FCS themes from UAT.

Storybook deployment

Storybook is deployed to GitHub Pages via a workflow action. This action will run on pushes to the master branch. When new PRs are merged to master the action should run on the merge commit and update the deployed version of Storybook. The deployed version lives here: GH Pages Storybook. The code for this action lives in .github/workflows/deploy-github-pages.yml.

Adding new components

• New components may be added to this library via pull request. Only components that are currently used in, or expected to be used in, more than one CB frontend should be present in this library. Very niche application specific components should be kept in the components/atoms and components/molecules directory of their parent application.

• Almost all components in this library, and almost all newly added components, should be as "dumb" as possible. Ideally avoid introducing components that have tight integrations with application state. Forms and form components that make use of redux-freeform are an exception to this rule.

• If a non-form component contains integration with application state, or business logic specific to a particular application, breaking the component up into styled/layout atoms and an application specific molecule that consumes them is the best practice. An example of this can be observed with the Header and Footer molecules in Navigate Frontend. Both of these molcules make use of component library atoms such as NavHeader to layout out content. NFE then has Header and Footer molecules which live in the NFE components directory and use NFE specific business logic to provide content to these atoms, resulting in a complete Header and Footer.

Adding Typescript declarations

Any components used in a Typescript app need a declaration file.

1. Create a index.d.ts file in the directory for that component that exports the typed component constant. Use the Expand interface found in ./src/util/expand so the full props will appear on hover in VSCode. Extend React.HTMLAttributes<HTMLElement>> to add all html props and event handlers. e.g.:

import React from "react";
import Expand from "../../../util/expand";

export interface ButtonWithActionProps {
  action?: React.SyntheticEvent;
  variant?: string;
  text?: string;
  textWrap?: boolean;
  isLoading?: boolean;
  textExtraStyles?: string;
  contentOverride?: boolean;
  extraStyles?: string;
  tabIndex?: number;
}

export const ButtonWithAction: React.FC<Expand<ButtonWithActionProps> &
  React.HTMLAttributes<HTMLElement>>;

2. Export the component from the index.d.ts in the top-level directory for your component, i.e. src/components/atoms/index.d.ts. e.g:

...
export * from "./button-with-action";
...

Version bumping and publishing

Version bumping and Publishing to NPM

• Authors of PRs are responsible for bumping the version of the package prior to merging an approved PR to master. Once your pending PR has been approved, before merging to master, run yarn build && yarn publish in the main directory to create and publish a new build to NPM. This step should happen immediately before you merge your PR to master, to minimize conflicts between built versions.

• CB Components follows semantic versioning practices, which divides version upgrades into three categories: "Patch" (e.g., 6.0.1 -> 6.0.2), "Minor" (e.g., 6.0.2 -> 6.1.0), and "Major" (e.g., 6.1.0 -> 7.0.0)

• Patch versions should consist of small, non-breaking changes to components, component stories, and development tooling or documentation; or bug fixes

  • Fixing a non-breaking bug, such as the border color of an input; adding an example to a component's storybook story; adding a new HTML attribute to an existing component are all examples of patch changes

• Minor versions consist of moderate, non-breaking changes and additions: alterations to existing component structure or theme files; addition of new components, stories, or dependencies; significant changes to development tooling or introduction of tests

  • Adding to, removing, or significantly changing a component's base-theme or themeable properties; adding a new version of a component triggered by an optional prop; adding a new dependency to the library; changing the Rollup build files or plugins; or adding new unit tests to one or more components are all examples of minor verison changes

• Major version relases should be reserved for breaking library changes: removal of in-use components; breaking changes to component layout or theme properties; addition or removal of crticial dependencies. These version increases should be rare.

  • Removing currently used components entirely, or removing versions of a component; significantly changing the structure, function, or API (props) of an existing component; removing existing library dependencies; adding a new peer dependency or moving a current library dependency to be a peer dep (such that the library breaks if a consuming application fails to provide the proper verison of that dependency) are all examples of major verison changes

• Because of the potential for disruption of applications running in PROD, any changes that will result in a Major version increase require notifying other frontend engineers at CB who own applications such as Navigate Frontend (NFE), Revenue Management Dashboard (RMD), or Point of Sale Frontend (POS-Frontend), or any future applications which consume CB Components in advance of the change being merged to master and a new version being released

Consuming in your application

Adding to existing application

• Run yarn add @thecb/components.
• To verify it installed successfully, make sure it is in the applicaton's package.json file.

Local import and development

If you are developing locally, you can add or make changes to components in the @thecb/components package and see those changes in the application running locally by linking the @thecb/components package to your application. Open the @thecb/components, and in the command line

• Run yarn build
• Run yarn link

You should see a success message, and directions on how to link this package into an application. In the application you’d like the components, navigate to that application and in the command line

• Run yarn link @thecb/components

Now the package is linked locally and you can make changes to the @thecb/components and you’ll see the changes in the application running @thecb/components. To unlink the package, in the application running @thecb/components and in the command line

• Run yarn unlink @thecb/components
• Run yarn install --``force

Next go to the @thecb/components and in the command line

• Run yarn unlink

Now the package is unlinked, and you’re using the version on NPM.

Yalc

If you encounter issues using yarn link, a nice alternative is yalc. See https://github.com/wclr/yalc for usage instructions.

Importing and using components

To use components, you need to import the desired components inside the file you’d like them in. For example, to import the <ButtonWithAction /> component into a file

• import { ButtonWithAction } from "``@thecb/components``"``;

You can alias the component by

• import { ButtonWithAction as MyButton } from "@thecb/components";

To import multiple components

• import { ButtonWithAction, LoginForm, Box, Stack, Cluster } from "@thecb/components";

Publishing Storybook to GitHub Pages

This is a test to see if the GH Actions publishing workflow is functional.