cerner / terra-core

Terra offers a set of configurable React components designed to help build scalable and modular application UIs. This UI library was created to solve real-world issues in projects we work on day to day.

Terra Core

• Packages
  • Versioning
  • Status
  • Deprecated
• Supported Browsers
• Internationalization (I18n)
  • Packages Requiring I18n
• Contributing
• Local Development
• Local Development using Docker (Dev Containers)
• LICENSE

Packages

Versioning

When a component reaches v1.0.0., it is considered to be stable and will follow SemVer for versioning.

1. MAJOR versions represent breaking changes
2. MINOR versions represent added functionality in a backwards-compatible manner
3. PATCH versions represent backwards-compatible bug fixes

Consult the component CHANGELOGs, related issues, and PRs for more information.

We view the React.js props API of our components as our main public API. We use this to guide us when versioning components.

Prior to components reaching v1.0.0, a component is considered to be in a beta stage. Components in beta stage may include breaking changes, new features, and bug fixes all within v0.x.x releases.

Status

Terra Package	Version	Status	Dependencies
terra-action-footer
terra-action-header
terra-alert
terra-arrange
terra-avatar
terra-badge
terra-base
terra-breakpoints
terra-button
terra-button-group
terra-card
terra-content-container
terra-demographics-banner
terra-dialog
terra-divider
terra-dropdown-button
terra-dynamic-grid
terra-form-checkbox
terra-form-field
terra-form-fieldset
terra-form-input
terra-form-radio
terra-form-select
terra-form-textarea
terra-grid
terra-heading
terra-hyperlink
terra-i18n
terra-icon
terra-image
terra-list
terra-mixins
terra-overlay
terra-paginator
terra-profile-image
terra-progress-bar
terra-responsive-element
terra-scroll
terra-search-field
terra-section-header
terra-show-hide
terra-signature
terra-spacer
terra-status
terra-status-view
terra-table
terra-tag
terra-text
terra-toggle
terra-toggle-button
terra-toggle-section-header
terra-visually-hidden-text

Deprecated

Terra Package	Version	Status	Dependencies
terra-form
terra-i18n-plugin
terra-legacy-theme
terra-modal

Supported Browsers

Browser	Version
Chrome & Chrome for Android	Current
Edge	Current
Firefox	Current
Internet Explorer	10 & 11
Safari & Mobile Safari	Current

Internationalization (I18n)

Please review Terra's Internationalization documentation for more information. Included are directions on consumption and how internationalization is setup.

Packages Requiring I18n

• terra-action-header
• terra-alert
• terra-demographics-banner
• terra-dialog
• terra-form-checkbox
• terra-form-field
• terra-form-radio
• terra-form-select
• terra-i18n
• terra-overlay
• terra-search-field
• terra-show-hide
• terra-status-view

Contributing

Please read through our contributing guidelines. Included are directions for issue reporting and pull requests.

Local Development

1. Install Node Version Manager (NVM) and Node. The root directory contains a .nvmrc file that specifies terra-core's node version. Once NVM is installed and you are within the root directory, your version of node will change to this version.
2. Install docker https://www.docker.com/ to run browser tests.
3. Install dependencies and run tests.

npm install
npm run test

Local Development using Docker (Dev Containers)

1. Install Rancher or Docker.
   • Rancher is free and open-source and is highly recommended whereas Docker may require a license for use.
2. Install Microsoft VS Code.
3. Install the Dev Container extension.
   • Navigate to View -> Extension -> Search for and install Dev Containers (or "ms-vscode-remote.remote-containers")
   • More information on Dev Containers
4. Build the dev container:
   • (Option 1) - Opening local workspace in dev container
     • Clone the repository (or fork) locally and open the project in Visual Studio Code
     • Navigate to View -> Command Palette and run Dev Containers: Open Workspace in Container
   • (Option 2) - Recommended for Windows for hot-reloading to work during development and improved performance: Creating the dev container using dev volumes (for more information and guidance, see the Official Guide)
     • If you have git setup and have global config file ~/.gitconfig locally, these settings should automatically be transferred to the dev container
     • Navigate to View -> Command Palette and run Dev Containers: Clone Repository in Container Volume
     • Paste the GitHub URL of this repository (or fork)
     • VS Code will now reload the workspace and create/start the dev container and volume
     • Please note: changes made using this option will only update files in the Docker volume. It is recommended to commit changes often in case the volume is deleted or dev container gets removed.
5. You're now running in a dev container. Use the terminal of the dev container in Visual Studio Code to issue any npm or bash commands.
6. Before running any WDIO tests, make sure to perform the following steps:
   • Open a new terminal (outside the dev container) and navigate to ".devcontainer/" path in your repository.
   • Execute the command "docker compose -f docker-compose-wdio.yml up". Selenium hub should spin up. Leave this running in the background. If you see errors saying "container name already exists", run "docker container prune" command followed by pressing "y" to clear up any unused containers and try running the previous command again.
   • You can now run npm run test:docker or npm run wdio:docker commands to run WDIO tests from inside the Dev Container.
   • NOTE: Optionally, if you want to run other WDIO commands in the dev container, you can also edit the root package.json file WDIO scripts to include --disableSeleniumService=true flag. This will disable the selenium service from spinning up again. For example:

     "scripts": {
      "wdio:lowlight": "terra wdio --disableSeleniumService=true --themes clinical-lowlight-theme"
      }

   • If any of the compose files were to be changed, you must refresh the docker container by deleting the corresponding existing docker images, then running the following command:

       docker compose -f <changed compose file name>.yml up

7. To terminate a dev container:
   • Use command line or Rancher/Docker Desktop OR
   • Using Visual Studio Code
     • Select the Remote Explorer icon in the Activity Bar or View -> Command Palette and run Remote Explorer: Focus on Containers View
     • Locate the terra-core_devcontainer or currently running dev container under "Dev Containers"
     • Right click and select Stop Container and close the workspace
       • You can also select Rebuild Container to restart the dev container
8. To reopen a dev container:
   • Existing local workspace (for Option 1)
     • Open the project in Visual Studio Code
     • Ensure the workspace contains the .devcontainer folder
     • Navigate to View -> Command Palette and run Dev Containers: Open Workspace in Container
   • Isolated dev container volume (for Option 2)
     • Open Visual Studio Code
     • Use the Remote Explorer icon in the Activity Bar or View -> Command Palette and run Remote Explorer: Focus on Containers View to view containers
     • Locate the terra-core_devcontainer under "Dev Containers"
     • Hover over the dev container and click the Folder icon labelled Open Folder in Container or by right clicking and selecting Open Folder in Container

LICENSE

Copyright 2017 - 2024 Cerner Innovation, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

terra-core's Issues

Migrate Phase 1 components

Description of Issue

We have a bunch of phase 1 components which just have .scss and html. We need to migrate these over to the open source repo so we can iterate on them. Below is a list of issue to migrate over these type of components.

• terra-content
• terra-image
• terra-menu
• terra-standout
• terra-application
• terra-title

Migrate terra-react-svg-loader into repo

Issue Description

We had created a webpack react-svg-loader when we initially worked on terra-icon, however we pulled it as we ran into various issues with testing it. This issue is for re-evaluating the loader and migrating that work into terra-core.

Issue Type

• New Feature
• Enhancement
• Bug
• Other

Expected Behavior

Ability to import an SVG icon and convert it to a react component on the fly via webpack loader.

Current Behavior

N/A

Migrate terra-title into repo

https://github.com/cerner/terra-title

Migrate terra-image into repo

https://github.com/cerner/terra-image

Look into drying up the npm-scripts used in each package

Issue Description

There are duplicate npm-scripts used across all terra-core packages. @ryanthemanuel had some ideas on ways we could reduce this duplication. Some options to look into are having all the scripts point to a .js file in the root directory for each script and using shelljs to run tasks. Another option is to investigate https://www.npmjs.com/package/npm-run to run tasks.

Issue Type

• New Feature
• Enhancement
• Bug
• Other

Expected Behavior

Duplicate npm-scripts are reduced

Current Behavior

Duplicate npm-scripts are in every package.json

Make doc site a package.

The documentation site currently has dependencies on terra-application, terra-legacy-theme, and terra-react-svg-loader. These dependencies cannot be bootstrapped if they live in the root directory. We need to move the documentation site into it's own package to keep these dependencies up to date.

Update jestconfig.json

I don't think this file is currently being used: https://github.com/cerner/terra-ui/blob/master/jestconfig.json.

Can we remove it?

Update packages scripts to use an abstraction

Currently, for each package we have

    "compile": "npm run compile:clean && npm run compile:build",
    "compile:clean": "rm -rf lib",
    "compile:build": "$(cd ..; npm bin)/babel src --out-dir lib --copy-files",
    "lint": "npm run lint:js && npm run lint:scss",
    "lint:js": "$(cd ..; npm bin)/eslint --ext .js,.jsx . --ignore-path ../../.eslintignore",
    "lint:scss": "$(cd ..; npm bin)/stylelint src/**/*.scss",
    "release:major": "npm test && node ../../scripts/release/release.js major",
    "release:minor": "npm test && node ../../scripts/release/release.js minor",
    "release:patch": "npm test && node ../../scripts/release/release.js patch",
    "test": "npm run test:spec && npm run test:nightwatch-default",
    "test:spec": "$(cd ..; npm bin)/jest --config ../../jestconfig.json",
    "test:all": "npm run test:nightwatch-default && npm run test:nightwatch-chrome && npm run test:nightwatch-firefox && npm run test:nightwatch-safari",
    "test:nightwatch-default": "node ../../scripts/nightwatch/nightwatch.js",
    "test:nightwatch-chrome": "node ../../scripts/nightwatch/nightwatch.js chrome",
    "test:nightwatch-firefox": "node ../../scripts/nightwatch/nightwatch.js firefox",
    "test:nightwatch-safari": "npm run test:nightwatch-safari-tiny && npm run test:nightwatch-safari-small && npm run test:nightwatch-safari-medium && npm run test:nightwatch-safari-large && npm run test:nightwatch-safari-huge && npm run test:nightwatch-safari-enormous",
    "test:nightwatch-safari-tiny": "$(cd ..; npm bin)/nightwatch --config tests/nightwatch.conf.js -e safari-tiny",
    "test:nightwatch-safari-small": "$(cd ..; npm bin)/nightwatch --config tests/nightwatch.conf.js -e safari-small",
    "test:nightwatch-safari-medium": "$(cd ..; npm bin)/nightwatch --config tests/nightwatch.conf.js -e safari-medium",
    "test:nightwatch-safari-large": "$(cd ..; npm bin)/nightwatch --config tests/nightwatch.conf.js -e safari-large",
    "test:nightwatch-safari-huge": "$(cd ..; npm bin)/nightwatch --config tests/nightwatch.conf.js -e safari-huge",
    "test:nightwatch-safari-enormous": "$(cd ..; npm bin)/nightwatch --config tests/nightwatch.conf.js -e safari-enormous"

If we need to change a script, we need to go update it in every single package. Instead, we should have the script in a single location and have all of the packages reference it. For example,

    "compile": "npm run compile:clean && npm run compile:build",

to

    "compile":  "node ../../scripts/compile/index.js"

yarn install => yarn add

We have several packages that have documentation that states yarn install terra-*. The correct syntax is yarn add terra-*.

https://github.com/cerner/terra-ui/blob/master/packages/terra-button/docs/README.md#getting-started

Update packages eslintignore to point to configuration in root

When running npm run lint in an individual package, the .eslitignore file is not honored.

Update

    "lint:js": "../../node_modules/.bin/eslint **/*.js, **/*.jsx",

to

    "lint:js": "../../node_modules/.bin/eslint **/*.js, **/*.jsx --ignore-path ../../.eslintignore",

Migrate terra-slide-panel into repo

https://github.com/cerner/terra-slide-panel

Add contributors names

Add existing contributors to contributors.md

Prepush script that involves testing doesn't succeed with SourceTree

Issue Description

Prepush script that involves testing doesn't succeed with SourceTree

Issue Type

• New Feature
• Enhancement
• Bug
• Other

Expected Behavior

Prepush script that involves testing succeeds with SourceTree

Current Behavior

SourceTree is not able this run this script successfully. git push is successful from the command line but pushing from SourceTree results in the following error:

git -c diff.mnemonicprefix=false -c core.quotepath=false -c credential.helper=sourcetree push -v origin refs/heads/ResponsiveElement:refs/heads/ResponsiveElement 
Pushing to [email protected]:cerner/terra-ui.git
error: failed to push some refs to '[email protected]:cerner/terra-ui.git'

> husky - npm run -s prepush


> husky - pre-push hook failed (add --no-verify to bypass)
> husky - to debug, use 'npm run precommit'
Completed with errors, see above

Steps to Reproduce

Environment

• Component Version:
• Browser Name and Version:
• Operating System and version (desktop or mobile):

Pin terra-components to single version to prevent duplicate versions in bundles

Based on the spike we did on versioning, we came to the conclusion to pin terra components referenced as dependencies, devDependencies, and/or peerDependencies to singular versions rather than allowing ^ or ~ usage on version numbers which would allow versions to be updated the most recent major or minor version. This is to prevent duplicate versions being compiled in the webpack bundle.

Pagination Component

Issue Description

Create pagination component.

Issue Type

• New Feature
• Enhancement
• Bug
• Other

Expected Behavior

Needs expected behavior defined

Current Behavior

N/A

Migrate terra-list into repo

https://github.com/cerner/terra-list

Migrate terra-progress-bar into repo

https://github.com/cerner/terra-progress-bar

Migrate terra-standout into repo

https://github.com/cerner/terra-standout

Migrate terra-mixins into repo

https://github.com/cerner/terra-mixins

Migrate terra-icon into repo

Migrate terra-menu into repo

https://github.com/cerner/terra-menu

Migrate terra-badge into repo

Set private: true to each package

Until we are ready to publish, set private: true in each package. This will prevent accidental publishing.
https://docs.npmjs.com/files/package.json

Move Markdown and PropsTable components into their own package.

Currently, terra-button has a devDependency on terra-site. terra-site also has a devDependency on terra-button. We should move the PropsTable and Markdown components currently in terra-site into their own package so there is not a circular dependency.

Investigate grid styles triggering horizontal scrollbar

Issue Description

When viewing the grid demos in storybook and prior to storybook, a horizontal scrollbar displays on the window.

Additional Details (optional)

The current implementation adds "grid gutters" via padding on both the left and right of columns. The outer padding on the first and last column should be canceled out by a negative left and right margin on the grid row. This is a popular approach taken by other frameworks. All of the other frameworks that use this approach are impacted by this issue as far as I could tell.

This issue is usually hidden by a container element which adds padding equal to or greater than the amount of the grid gutter. The container essentially consumes the space of the negative margins, eliminating the need for a horizontal scrollbar.

In legacy terra, we apply grid gutter spacing by applying it as left padding on columns. The left padding on the first column is then canceled out by a negative left margin on the row. This approach seems to achieve the same visual without triggering a horizontal scrollbar. This link describes some of the logic behind the legacy terra grid styling around this behavior: https://csswizardry.com/2011/08/building-better-grid-systems/

Issue Type

• New Feature
• Enhancement
• Bug
• Other

Expected Behavior

No horizontal bar appears on window when using grid

Current Behavior

Horizontal bar appears on window when using grid when there is no margin/padding on the html or body element.

Steps to Reproduce

1. Navigate to page to view grid examples

Environment

• Component Version: v1.0.0
• Browser Name and Version: All browsers
• Operating System and version (desktop or mobile):

Add LICENSE and NOTICE files to individual packages.

In the multi-repos, we had a LICENSE and NOTICE file. As we migrated some of the components to the monorepo, we removed these files as the thought was that they could live in the root directory of terra-ui. Thinking on this more, we need these files in the individual package directories so they are included in the distributed npm packages.

To Do

• Add LICENSE and NOTICE files to the following packages.

• terra-arrange
• terra-badge
• terra-button
• terra-grid
• terra-mixins
• terra-toolkit

Migrate terra-legacy-theme into repo

https://github.com/cerner/terra-legacy-theme

Add task to remove lib directory before compile

npm run compile will transpile our js and copy files into the lib directory. Old files will persist unless we remove them. Before compiling, we should clean out the lib directory.

Migrate terra-grid into repo

Travis-ci: Cache node_modules

Cache node_modules to speed up testing
https://blog.travis-ci.com/2013-12-05-speed-up-your-builds-cache-your-dependencies

Migrate terra-status into repo

https://github.com/cerner/terra-status

Migrate terra-content into repo

https://github.com/cerner/terra-content

Add src to .npmignore

Description of Issue

A common pattern for npm modules is to add the lib(es5) directory to the .gitignore and add the src(es6) directory to the .npmignore. Babel is an example of this pattern that also uses lerna.

More information can be found in this article:
http://jamesknelson.com/writing-npm-packages-with-es6-using-the-babel-6-cli/

• Add a .npmignore file to each package that contains the src directory.

Update Component Naming

https://github.com/cerner/terra-ui/tree/master/packages/terra-button/src

/src/
  Button.jsx
  Button.scss

https://github.com/cerner/terra-ui/tree/master/packages/terra-arrange/src

/src/
  Arrange.jsx
  Arrange.scss

Add clean task to remove obsolete snapshots

Remove contributing and supported browsers from package readme

Contributing and Supported Browsers will live in the root directory. We don't need it in every package.

Update paths

Update

'../../../packages/terra-site/src/PropsTable';

to

'terra-site/src/PropsTable';

This will help ensure our packages will work outside the monorepo.

Any relative paths can be replaced by adding the package as a devDependency and referencing it directly.

Update package README files to point to new repo

Description of Issue

The README inside of packages/terra-component/docs/ and the README in packages/terra-component/, there are references to the old repos.

These files include the following lines:

- [Download the latest version](https://github.com/cerner/terra-arrange/archive/master.zip)
- Clone the repo: `git clone https://github.com/cerner/terra-arrange.git`

These need to be updated to the following:

- [Download the latest version](https://github.com/cerner/terra-ui/archive/master.zip)
- Clone the repo: `git clone https://github.com/cerner/terra-ui.git`

• terra-arrange
• terra-button
• terra-grid

TODO:
Add other repos we need to do this for to checklist.

Migrate terra-application into repo

https://github.com/cerner/terra-application

Remove all obsolete snapshots

Snapshot Summary
 › 36 obsolete snapshots found, run with `npm test -- -u` to remove them.

To remove obsolete snapshots, the script above must be executed in each package. It would be convenient to have the option of removing all obsolete snapshots in the repository.

Only lint/test packages that have impacted tests

Issue Description

Linting/Testing is starting to take a bit of time. We should investigate only testing packages that have impacted tests.

Issue Type

• New Feature
• Enhancement
• Bug
• Other

Expected Behavior

Only lint/test packages that have modified code.

Current Behavior

CI runs lint/tests for all packages.

Update gh-pages when pushing to master

Issue Description

When merging branches to master, we have to manually deploy the changes. This is something that could be automated with Travis CI.

Issue Type

• New Feature
• Enhancement
• Bug
• Other

Expected Behavior

When merging branches to master, I would like to automate deploying to gh-pages.

Current Behavior

Need to manually deploy changes to master to gh-pages.

Update RELEASE.md

Description of Issue

The instructions in RELEASE.md have grown out of date with the changes to a monorepo and addition of our release scripts.

We should just document what process we go through when we release the next component and update this file with those instructions.

Expected Outcomes

• RELEASE.md is updated with doc on usage of the release scripts within the package.json

Add responsive block button behavior

Issue Description

From PR for uplifting component to react component, there is a need for a responsive block button. This would be a button that displays as a block button at a set screen width and a normal button at another screen width. More details are needed on the specific requirements for this feature.

Issue Type

• New Feature
• Enhancement
• Bug
• Other

Expected Behavior

A button that displays as a block button at a set screen width and a normal button at another screen width.

Current Behavior

N/A

Migrate terra-table into repo

https://github.com/cerner/terra-table

Update urls in packages package.json

https://github.com/cerner/terra-ui/blob/master/packages/terra-button/package.json#L9
https://github.com/cerner/terra-ui/blob/master/packages/terra-arrange/package.json#L9

Migrate terra-button-group into repo

https://github.com/cerner/terra-button-group

Migrate terra-alert into repo

https://github.com/cerner/terra-alert

Migrate terra-modal into repo

https://github.com/cerner/terra-modal

Add prepush hook

I would like to automate testing, linting, and compiling before any git pushes.

https://github.com/typicode/husky