Cardinal Design System

Description

This repository houses both the Cardinal catalog application and the components and styles presented therein. The Cardinal components, styles, and config items can be found in the projects/cardinal directory.

Consuming Cardinal Packages

Cardinal components, styles, and configuration items are consumable via npm, and can be installed following the format: npm install @cardinal/button, npm install @cardinal/grid, npm install @cardinal/tslint-config, etc. In order to tell NPM where to find the packages, an entry in your npmrc file is required: @cardinal:registry=http://nexus.us.aegon.com/repository/transamerica.digital.ui.release

Catalog Development

Run npm start to launch the catalog application locally. This will automatically launch a browser window to http://localhost:4200/, where the application is hosted. The app will automatically reload if you change any of the source files.

Component Development

Cardinal leverages Angular Elements to create framework agnostic HTML5 Custom Elements.

New Components

The project setup can be a bit complicated for creating elements at the moment, so the best solution is to model after a previously created example. We hope to leverage Angular Scematics to improve this part of the process in future releases.

Developing Components

In order to have live-reload functionality for a component under development, ensure that the project is properly configured in angular.json, then add an entry in the catalog application's scripts section that points to the component's distribution directory e.g: dist/cardinal/button. Then run npm run develop-component [component name]. This will run a live reloading build for the component and launch a watcher to handle concatenating the resulting js into the dist location. Then run npm start in another terminal for running the app as usual. Changes to the component code will then automatically load in the application.

Publishing

The publishing strategy for Cardinal doesn't fit into the strategies currently provided by the Angular Client, so some addition scripting is needed to accomplish the release of packages. In order to release, create a directory in the projects/cardinal/packages directory named after the component. Include in this directory a package.json for the project. Once properly configured, Jenkins will use the publishing scripts to handle the rest. The package.json should contain any peer dependencies, name, version, and a type of either: component, style, or config. e.g:

{
  "name": "@cardinal/button",
  "version": "0.0.3",
  "type": "component"
}

Publishing Components

For publishing components the only requirements are the package.json file and proper configuration elsewhere. The package directory name must match the name of the project in angular.json and the tmp build directory listing in the project's output directory. The build script will build any component with the correct name in the project/cardinal/src/components directory.

Publishing Styles

Since the Cardinal styles are not a part of the angular build process, an extra file is required to publish. The file name must be [package name].package.scss and is essentially an index to the scss files that you wish to be included in the package. This file will be used to bundle the file list within, and then the resulting file will be built to css and published. Source for styles reside in the project/cardinal/src/styles directory.

Publishing Config Files

To publish config files, simply ensure that the file to be published is in the projects/cardinal/src/config directory and is named the same as the package. Currently, only .json files are supported, but this can be expanded with simple changes to the publish script.

Testing Publish Files

Commit and save work BEFORE running this script. To test files publishing to npm, double check all nessessary and expected files are included in the files property of the package.json file and included in any imports. run npm run publish:local. Warning: this script strips your package.json file and runs other project specific build strategies.

E2E Testing with Cypress

Run npm run cypress-ui to launch the Cypress test suite.

Running with Docker

The project is deployed to production using Docker. To run the project via Docker locally:

• install docker on your machine using these instructions
• run npm install
• run npm run build-prod
• run docker build -t ds-catalog
• running docker images will then display your newly created image
• run docker run -d --restart=always -p 8080:80 ds-catalog to start the docker image on port 8080
• to view running containers run docker ps
• to stop a running container (useful for freeing the port) run docker stop [container id] where container ID is listed by the docker ps command
• to use the command line in a running container, run docker exec -it [container id] bash

Unit Testing

Run npm test to execute the catalog application tests and npm test [component name] to test Cardinal components.