@thecb/components 2.3.0 → 3.1.3

package/.github/workflows/bump-version.yml

@@ -0,0 +1,30 @@
+name: Bump Package Version
+on:
+  push:
+    branches:
+      - "master"
+    
+jobs:
+  bump-version:
+    name: Bump version on master
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v2
+        with:
+          ref: ${{ github.ref }}
+      - name: "cat package.json"
+        run: cat ./package.json
+      - name: Setup Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: 12
+      - name: Automated version bump
+        uses: phips28/gh-action-bump-version@master
+        with:
+          tag-prefix: ''
+        env:
+          GITHUB_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
+      - name: "cat package.json"
+        run: cat ./package.json

package/.github/workflows/create-release/build-body.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+# The output is a Markdown table with columns for the PR (with a link),
+# a branch, and JIRA ticket with link (if available).
+#
+# If the branch name starts with an id for a JIRA ticket (e.g.,
+# PLAT-123), then a link to the ticket is created.  Otherwise this
+# column is blank.
+#
+# A link to the branch isn't valuable because they are usually
+# deleted after merging.
+
+from_tag=${FROM_TAG}
+to_tag=${TAG##*/}
+
+echo "## Changes"
+echo ""
+echo "### PRs"
+# all merge commits, only merge commits
+git --no-pager log --merges --format='%s' ${from_tag}..${to_tag} | \
+    # only pull-request merges
+    grep "Merge pull request" | \
+    gawk 'BEGIN { print "| PR | Branch | Ticket |" ;
+                  print "| -- | ------ | ------ |" }
+          {if (match($0,/(#[0-9]+).*CityBaseInc\/(([A-Z]+-[0-9]+)\S+)/,m))
+            printf "| %s | %s | [%s](https://citybase.atlassian.net/browse/%s) |\n", m[1], m[2], m[3], m[3] }
+          {if (match($0,/(#[0-9]+).*CityBaseInc\/([a-z]\S+)/,m))
+            print "|", m[1], "|", m[2], "|", "|"}'
+
+echo ""
+echo "### Code Diff"
+echo "https://github.com/${REPO}/compare/${from_tag}..${to_tag}"
+echo ""
+
+git show ${to_tag} --format=short | grep Tagger

package/.github/workflows/create-release.yml

@@ -0,0 +1,52 @@
+on:
+  push:
+    tags:
+      - '*'
+
+
+name: Create Release
+
+jobs:
+  build:
+    name: Create Release
+    runs-on: ubuntu-latest
+    env:
+      REPO: ${{ github.repository }}
+      TAG: ${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Get latest release
+        id: get_latest
+        run: |
+          tag_name=$(curl --silent --request GET \
+          --url https://api.github.com/repos/${{ github.repository }}/releases/latest \
+          --header "authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+          --header "content-type: applicatoin/json" | jq -r .tag_name)
+          echo "::set-output name=tag_name::$tag_name"
+      - name: Fetch branches
+        run: git fetch --all --prune --unshallow
+      - name: Fetch tags
+        run: git fetch --unshallow origin +refs/tags/*:refs/tags/*
+      - name: Checkout master
+        run: git checkout master
+      - name: Build body
+        id: build_body
+        env:
+          FROM_TAG: ${{ steps.get_latest.outpus.tag_name}}
+        run: |
+          body=$(sh ./.github/workflows/create-release/build-body.sh)
+          body="${body//'%'/'%25'}"
+          body="${body//$'\n'/'%0A'}"
+          body="${body//$'\r'/'%0D'}"
+          echo "::set-output name=body::$body"
+      - name: Create Release
+        id: create_release
+        uses: actions/create-release@4d1b6075ce7561b672b8552148edec2f27584fe9
+        env:
+          GITHUB_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
+        with: 
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+          body: ${{ steps.build_body.outputs.body }}
+          draft: false
+          prerelease: false

package/.github/workflows/disabled-workflows/publish-update.yml

@@ -0,0 +1,73 @@
+name: Publish and Update
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          ref: master
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v1.2.0
+        with:
+          node-version: "10.x"
+
+      - name: Install dependencies
+        run: yarn install --silent
+
+      - name: Compile build
+        run: yarn build --silent
+
+      - name: Commit changes
+        uses: EndBug/add-and-commit@v2.1.0
+        with:
+          author_name: CB Feeps
+          author_email: feeps@thecitybase.com
+          message: "[auto] Update dist"
+          path: dist
+          pattern: "*.*"
+          force: true
+          ref: deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
+
+  publish:
+    name: Publish to NPM Registry
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          ref: deploy
+
+      - name: Set up Node.js for NPM
+        if: steps.check.outputs.changed == 'true'
+        uses: actions/setup-node@v1.2.0
+        with:
+          node-version: "10.x"
+          registry-url: "https://registry.npmjs.org"
+          scope: "@thecb"
+
+      - name: Install dependencies
+        if: steps.check.outputs.changed == 'true'
+        run: yarn install
+
+      - name: Create build
+        if: steps.check.outputs.changed == 'true'
+        run: yarn build
+
+      - name: Publish package to NPM
+        if: steps.check.outputs.changed == 'true'
+        run: yarn publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.storybook/main.js

@@ -0,0 +1,4 @@
+module.exports = {
+    stories: ['../src/**/*.stories.[tj]s'],
+    addons: ['@storybook/addon-knobs/register']
+};

package/.storybook/page.js

@@ -0,0 +1,61 @@
+import React from "react"
+import { ThemeProvider } from "styled-components"
+import { withKnobs, select, radios, text } from "@storybook/addon-knobs";
+import { Provider } from 'react-redux';
+import { createStore } from "redux";
+import { Router } from "react-router-dom";
+import { createBrowserHistory } from "history";
+
+import ResizingContainer from "../src/components/atoms/layouts/examples/ResizingContainer";
+import { SFTheme, APCTheme } from "./themes";
+
+const themesLabel = "Theme";
+const themes = {
+  SF: SFTheme,
+  APC: APCTheme,
+  None: {},
+};
+const defaultValue = SFTheme;
+const groupId = "Theme";
+
+const animateLabel = "Animate";
+const animateOptions = {
+  play: "play",
+  pause: "pause"
+};
+const animateDefaultValue = "pause";
+const animateGroupID = "Container";
+
+const themeDecorator = storyFn => (
+  <ThemeProvider theme={select(themesLabel, themes, defaultValue, groupId)}>{storyFn()}</ThemeProvider>
+)
+
+export default ({ title, Component, reducer = () => { }}) => {
+  const history = createBrowserHistory();
+  const store =createStore(
+    reducer,
+    window.__REDUX_DEVTOOLS_EXTENSION__ && window.__REDUX_DEVTOOLS_EXTENSION__()
+  )
+  return {
+    title,
+    component: Component,
+    decorators: [
+      themeDecorator,
+      withKnobs,
+      storyFn => (
+        <Router history={history} >
+          <Provider store={store}>
+              <div style={{ height: "600px", display: "flex", justifyContent: "center", flexDirection: "column" }}>
+                <ResizingContainer
+                  animate={radios(animateLabel, animateOptions, animateDefaultValue, animateGroupID)}
+                  containerMax={text("Container Max", "40rem", animateGroupID)}
+                  containerMin={text("Container Min", "20rem", animateGroupID)}>
+                  {storyFn()}
+                </ResizingContainer >
+              </div>
+          </Provider>
+        </Router>
+      )
+    ]
+  }
+};

package/.storybook/themes/apc.theme.js

@@ -0,0 +1 @@
+export const APCTheme = {values: {"Button":{"active":{"primary":"background-color: #C8171E; border: 2px solid #C8171E; box-shadow: 0 0 10px #E30100;","secondary":"background-color: #F58D91; color: #FF0000; box-shadow: 0 0 10px #FF0000","smallPrimary":"background-color: #C8171E; border: 2px solid #C8171E;  box-shadow: 0 0 10px #E30100","smallSecondary":"background-color: #F58D91; color: #FF0000; box-shadow: 0 0 10px #FF0000"},"backgroundColor":{"primary":"#EC1C24","secondary":"#F6F6F9","smallPrimary":"#EC1C24","smallSecondary":"#F6F6F9"},"border":{"primary":"2px solid #EC1C24;","secondary":"2px solid #EC1C24;","smallPrimary":"2px solid %#EC1C24;","smallSecondary":"2px solid #EC1C24;"},"color":{"primary":"#F6F6F9","secondary":"#EC1C24","smallPrimary":"#F6F6F9","smallSecondary":"#EC1C24"},"focus":{"primary":"outline: none; background-color: #C8171E; border: 2px solid #C8171E; box-shadow: 0 0 10px #E30100","secondary":"outline: none; background-color: #F58D91; color: #FF0000; box-shadow: 0 0 10px #FF0000;","smallPrimary":"outline: none; background-color: #C8171E; border: 2px solid #C8171E; box-shadow: 0 0 10px #E30100","smallSecondary":"outline: none; background-color: #F58D91; color: #FF0000; box-shadow: 0 0 10px #FF0000;"},"hover":{"primary":"cursor: pointer; background-color: #E30100; border: 2px solid #E30100; box-shadow: 0 0 10px #E30100;","secondary":"cursor: pointer; background-color: #FBD9D9; box-shadow: 0 0 10px #EC1C24; color: #EC1C24;","smallPrimary":"cursor: pointer; background-color: #E30100; border: 2px solid #E30100; box-shadow: 0 0 10px #E30100;","smallSecondary":"cursor: pointer; background-color: #FBD9D9; box-shadow: 0 0 10px #EC1C24; color: #EC1C24;"}},"Footer":{"backgroundColor":"#56575B"},"Header":{"backgroundColor":"#FFFFFF"},"HighlightTabRow":{"backgroundColor":"#215B9E"},"linkColor":"#15749D","logo":"logo.png","primaryColor":"#3B414D","secondaryColor":"#E5E7EC","textColor":"#000000"}}

package/.storybook/themes/index.js

@@ -0,0 +1,2 @@
+export { SFTheme } from "./sf.theme"
+export { APCTheme } from "./apc.theme"

package/.storybook/themes/sf.theme.js

@@ -0,0 +1 @@
+export const SFTheme = {values: {"AmountCallout":{"color":"#347BB2"},"Breadcrumb":{"color":"#347BB2"},"Button":{"active":{"danger":"background-color: #870000; border: 2px solid #870000; box-shadow: 0 0 10px #ED125F;","ghost":"background-color: $(transparent)s; color: #001952; box-shadow: none;","primary":"background-color: #001952; border: 2px solid #001952; box-shadow: 0 0 10px #347BB2","secondary":"background-color: #D8E5F2; box-shadow: 0 0 10px #D8E5F2;","smallGhost":"background-color: $(transparent)s; color: #001952; box-shadow: none;","smallPrimary":"background-color: #001952; border: 2px solid #001952; box-shadow: 0 0 10px #347BB2;","smallSecondary":"background-color: #D8E5F2; box-shadow: 0 0 10px #D8E5F2;"},"backgroundColor":{"danger":"#ED125F","ghost":"transparent","primary":"#347BB2","secondary":"transparent","smallGhost":"transparent","smallPrimary":"#347BB2","smallSecondary":"transparent"},"border":{"danger":"2px solid #ED125F;","ghost":"none","primary":"2px solid #347BB2;","secondary":"2px solid #347BB2;","smallGhost":"none","smallPrimary":"2px solid #347BB2;","smallSecondary":"2px solid #347BB2;"},"color":{"danger":"#FFFFFF","ghost":"#347BB2","primary":"#FFFFFF","secondary":"#347BB2","smallGhost":"#347BB2","smallPrimary":"#FFFFFF","smallSecondary":"#347BB2"},"disabled":{"danger":"background-color: #6E727E; border: 2px solid #6E727E; &:focus { box-shadow: 0 0 10px #6E727E; }","ghost":"color: #6E727E; border: none","primary":"background-color: #6E727E; border: 2px solid #6E727E; &:focus { box-shadow: 0 0 10px #6E727E; }","secondary":"background-color: #6E727E; border: 2px solid #6E727E; &:focus { box-shadow: 0 0 10px #6E727E; }","smallGhost":"color: #6E727E; border: none;","smallPrimary":"background-color: #6E727E; border: 2px solid #6E727E; &:focus { box-shadow: 0 0 10px #6E727E; }","smallSecondary":"background-color: #6E727E; border: 2px solid #6E727E; &:focus { box-shadow: 0 0 10px #6E727E; }"},"focus":{"danger":"outline: none; background-color: #BA002C; border: 2px solid #BA002C; box-shadow: 0 0 10px #ED125F","ghost":"outline: none; box-shadow: none; color: #024C85;","primary":"outline: none; background-color: #024C85; border: 2px solid #024C85; box-shadow: 0 0 10px #347BB2","secondary":"outline: none; background-color: #EAF2F8; box-shadow: 0 0 10px #EAF2F8;","smallGhost":"outline: none; box-shadow: none; color: #024C85;","smallPrimary":"outline: none; background-color: #024C85; border: 2px solid #024C85; box-shadow: 0 0 10px #347BB2","smallSecondary":"outline: none; background-color: #EAF2F8; box-shadow: 0 0 10px #EAF2F8;"},"hover":{"danger":"background-color: #BA002C; border: 2px solid #BA002C; box-shadow: 0 0 10px #ED125F;","ghost":"cursor: pointer; color: #024C85;","primary":"cursor: pointer; background-color: #024C85; border: 2px solid #024C85; box-shadow: 0 0 10px #347BB2","secondary":"cursor: pointer; background-color: #EAF2F8; box-shadow: 0 0 10px #EAF2F8;","smallGhost":"cursor: pointer; color: #024C85;","smallPrimary":"cursor: pointer; background-color: #024C85; border: 2px solid #024C85; box-shadow: 0 0 10px #347BB2","smallSecondary":"cursor: pointer; background-color: #EAF2F8; box-shadow: 0 0 10px #EAF2F8;"}},"Checkbox":{"boxShadow":{"default":"0 0 0 3px #D8E5F2;"},"checkedStyles":{"default":"background: #347BB2; border: 1px solid #347BB2;"}},"Dropdown":{"hoverColor":"#EFFAFF","selectedColor":"#347BB2"},"Footer":{"backgroundColor":"#182848","logoHeight":"52px","subfooterColor":"#347BB2"},"FormInput":{"hoverFocusStyles":{"default":"outline: none; text-decoration: underline; color: #024C85;"},"linkColor":{"default":"#347BB2"}},"Global":{"baseFontSize":"16px","baseMobileFontSize":"14px","pageBackground":"#F6F6F9"},"Header":{"backgroundColor":"#347BB2"},"Icons":{"accentColor":{"error":"#3B414D","info":"#3B414D","success":"#3B414D"},"primaryColor":{"error":"#FFFFFF","info":"#FFFFFF","success":"#FFFFFF"},"singleIconColor":{"darkMode":"#FFFFFF","primary":"#347BB2","secondary":"#3B414D"},"subIconColor":{"error":"#ED125F","info":"#347BB2","success":"#317D4F"}},"ModalLink":{"linkColor":"#347BB2"},"NavMenu":{"backgroundColor":"#347BB2"},"ProfileTab":{"activeTabAccent":"#347BB2","activeTabBackground":"#FFFFFF","activeTabHover":"#D8E5F2"},"RadioButton":{"activeColor":"#347BB2"},"Spinner":{"color":"#347BB2"},"ToggleSwitch":{"onBackground":"#347BB2"},"Workflow":{"accentColor":"#214566","fontFamily":"Open Sans, sans-serif","linkColor":"#214566","primaryButtonColor":"#347BB2","secondaryButtonColor":"#347BB2","textColor":"#091325","workflowFooterColor":"#182848","workflowHeaderColor":"#347BB2"},"linkColor":"#15749D","logo":"logo.png","primaryColor":"#3B414D","secondaryColor":"#E5E7EC","textColor":"#000000"}}

package/README.md

@@ -1,29 +1,25 @@
-# Citybase JS Components
+# Citybase Components
 
-This should be used for basic components that can be reused across applications with a standardized set of functionality hooks and props and base styles.
+This library contains Citybase React components for use across all current and future CB applications (NFE, RMD, Kiosk, POS).
 
 <!-- TOC -->
 
-- [Setup](#setup)
-- [Testing](#testing)
-- [Base Styles for components](#base-styles-for-components)
+- [Development setup](#development-setup)
+- [Component styles](#component-styles)
 - [Storybook](#storybook)
-  - [Storybook QA Environment](#storybook-qa-environment)
   - [Storybook addons](#storybook-addons)
-- [Deploying new changes](#deploying-new-changes)
+- [Adding new components](#adding-new-components)
+- [Version bumping and publishing](#version-bumping-and-publishing)
+  - [Version bumping](#version-bumping)
+  - [Publishing new versions to NPM](#publishing-new-versions-to-npm)
 - [Consuming in your application](#consuming-in-your-application)
-  - [Prod import](#prod-import)
-  - [Local import](#local-import)
-  - [Package.json updates](#packagejson-updates)
-  - [Circle CI needed setup](#circle-ci-needed-setup)
-- [Using in your application](#using-in-your-application)
-- [Wikitext Component Markdown](#wikitext-component-markdown)
-- [Listview Component Table](#listview-component-table)
-- [ExternalRedirect link protection library](#externalredirect-link-protection-library)
-
+  - [Adding to existing application](#adding-to-existing-application)
+  - [Local import and development](#local-import-and-development)
+  - [Importing and using components](#importing-and-using-components)
+  
 <!-- /TOC -->
 
-## Setup
+## Development setup
 
 - Install Node.js with [asdf](https://citybase.atlassian.net/wiki/spaces/DEV/pages/49777332/First+Time+Environment+Setup) by running `asdf install`
 - `brew install yarn && yarn`
@@ -32,118 +28,100 @@ The following statement will inheritly be called with `yarn`, but you can run it
 
 - `yarn run build`
 
-## Testing
-
-- All components are to have specs with coverage to 100%.
-  - Specs are to be added to the `__tests__` folder with an extension of `.spec.js`
-
-## Base Styles for components
+## Component styles
 
-- If a component needs base styles from the library to be exposed, please add to the root component folder with the extension of `.css`
-  - This will be the current direction of including styles until [IMP-857](https://citybase.atlassian.net/browse/IMP-857) is fully fleshed out and implemented.
+- 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.
 
-Example directory structure -
+- 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
 
-```
-citybase_js_components
-  |- .storybook-stories
-    |- component.js
-  |- src
-    |- component
-      |- __tests__
-        |- component.spec.js
-      component.css
-      component.js
-      component.types.js
-      index.js
-```
+- 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.
 
-CLI -
-Run all tests and produce a code coverage report.
+- 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.
 
-- `yarn test`
-  Run Jest in "watch mode" and do not produce a code coverage report. (Useful while writing new tests.)
-- `yarn run jest --watch --coverage=false`
+- 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](https://storybook.js.org/basics/guide-react/) for interactive component display.
 
-### Storybook QA Environment
-
-[https://js-assets.qa.citybase.thecb.net/](https://js-assets.qa.citybase.thecb.net/)
-
 ### Storybook addons
 
 - [Actions](https://github.com/storybooks/storybook/tree/master/addons/actions)
 - [Knobs](https://github.com/storybooks/storybook/tree/master/addons/knobs)
 
-Please include new component stories as this library will also be a sandbox. **Please consider these as important as unit tests.**
+Please include new component stories as this library will also be a sandbox.
 
 - `yarn storybook`
 - open browser to localhost:9001
 
-## Deploying new changes
+## Adding new components
 
-After new changes are ready to be deployed:
+- 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.
 
-- `yarn build`
-- [Tag off changes on Github](https://github.com/CityBaseInc/citybase_js_components/releases)
+- 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. 
 
-## Consuming in your application
+- 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`.
+
+## Version bumping and publishing
+
+### Version bumping
+
+- The version of the package is automatically bumped via GitHub Action after a pull request is merged to the master branch.
 
-### Prod import
+- The auto version bump action analyzes commit messages in the PR to determine what value to increment the package by. Including the keyword `major` in a commit message will result in a major version bump (i.e., `2.3.0` -> `3.0.0`). Including the keyword `minor` will result in a minor version bump (i.e., `2.3.0` -> `2.4.0`). PRs that are merged with neither the `major` or `minor` keywords present in commit messages will result in a patch version bump (i.e., `2.3.0` -> `2.3.1`).
+
+- Patch versions should consist of small, non-breaking changes to components, component stories, and development tooling or documentation; or bug fixes
+
+- 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
+
+- 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.
+
+### Publishing new versions to NPM
+
+- While GitHub will handle bumping the version of the library with every PR merge to master, publishing an update version of the library to NPM requires creating a release using the `release` script. This script triggers an action in the repo to create a release tagged with a publication date. After a new release is created, an action checks to see whether the library version differs from that on NPM. If the library version has changed, the action attempts to publish the new version to NPM.
+
+- Once a new version of the library is published to NPM, you may either manually update your application's `package.json` to request that new version, or wait until the following morning when dependabot will pick up the change and create an update PR for you.
+
+## Consuming in your application
 
-- `npm i git+ssh://git@github.com:CityBaseInc/citybase_js_components.git#<commit-ish> --save`
-- I would suggest using a tagged version of the component library as the default (master branch) can be unstable.
-- Learn more about [Git urls as dependencies](https://docs.npmjs.com/files/package.json#git-urls-as-dependencies)
+### Adding to existing application
 
-### Local import
+- Run `yarn add @thecb/components`. 
+- To verify it installed successfully, make sure it is in the applicaton's `package.json` file.
 
-- `npm i ../local/path/to/citybase_js_components --save`
-- This should persist changes up through the consuming application so that you don't have to rebuild and re `npm install` on every change.
+### Local import and development
 
-### Package.json updates
+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
 
-As the citybase_js_components is not built and delivered from a package manager, when the package is imported, it will serve up raw source files. You will likely need to update your package.json file to include any `citybase` labelled node_module package to use your babel processor.
+- Run `yarn build`
+- Run `yarn link`
 
-```javascript
-// in package.json
-{
-  test: /\.jsx?$/,
-  exclude: /node_modules\/(?!citybase).*/,
-  use: ['babel-loader'],
-},
-```
+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
 
-### Circle CI needed setup
+- Run `yarn link @thecb/components`
 
-Please follow
-[this step by step document](https://citybase.atlassian.net/wiki/spaces/DEV/pages/276267015/How+to+set+up+CircleCI+to+have+permissions+from+multiple+repos) on how to allow CircleCI to reference multiple repositories
+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
 
-## Using in your application
+- Run `yarn unlink @thecb/components`
+- Run `yarn install` `--``force`
 
-- `import { Button } from 'citybase_js_components';`
-- or alias the component:
-- `import { Button as CBButton } from 'citybase_js_components';`
+Next go to the `@thecb/components` and in the command line
 
-## Wikitext Component Markdown
+- Run `yarn unlink`
 
-The wikitext uses showdownjs to render markdown to html.
+Now the package is unlinked, and you’re using the version on NPM.
 
-- Syntax docs can be found here: https://github.com/showdownjs/showdown/wiki/Showdown's-Markdown-syntax
-- Live editor: http://demo.showdownjs.com/
-- Showdownjs documentation: https://github.com/showdownjs/showdown/wiki
+### Importing and using components
 
-## Listview Component Table
+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
 
-The listview component uses React-Table as the brains of the table.
+- `import { ButtonWithAction } from` `"``@thecb/components``"``;`
 
-- Live table: https://react-table.js.org/
-- Documentation: https://github.com/react-tools/react-table
+You can alias the component by 
 
-## ExternalRedirect link protection library
+- `import { ButtonWithAction as MyButton } from "@thecb/components";`
 
-This lib helps prevent against reverse tabnabbing.
+To import multiple components
 
-- Blankshield: https://github.com/danielstjules/blankshield
+- `import { ButtonWithAction, LoginForm, Box, Stack, Cluster } from "@thecb/components";`