# Ember HK Components

Reusable Ember components for Heroku applications.

## Assumptions

Usage of these components assumes you are using the [Purple3 CSS framework](https://purple3.herokuapp.com/) and [Malibu](https://hk-malibu.herokuapp.com).

## Security

This project maintains high security standards and regularly addresses vulnerabilities through:

- **Automated vulnerability scanning** via `pnpm audit`
- **Strategic dependency resolutions** to address transitive vulnerabilities
- **Regular dependency updates** while maintaining compatibility
- **Comprehensive security documentation** (see `BABEL_TRAVERSE_VULNERABILITY_GUIDE.md`)

For security-related questions or to report vulnerabilities, please follow Heroku's security guidelines.

## Usage

### Installation

1. Install `ember-cli-eyeglass` if it's not installed already:
   ```bash
   ember install ember-cli-eyeglass
   ```

2. Install `@heroku/ember-hk-components`:
   ```bash
   ember install @heroku/ember-hk-components
   ```

#### CSS

You'll need to import the scss files that support the actual components into your app. Ensure that you have installed `ember-cli-eyeglass` and that you are
using `app.scss` for your app's styles.

You can import css for _all_ the components like this:

`@import "ember-hk-components/ember-hk-components";`

If you want to import the css for only a specific component, like `hk-slide-panel`, you can include it like this:

`@import "ember-hk-components/hk-slide-panel";`

### Components

See [ember-hk-components.herokuapp.com](https://ember-hk-components.herokuapp.com) for a complete list of components that are available.

## Development

### Installation

* `git clone https://github.com/heroku/ember-hk-components`
* `cd ember-hk-components`
* Install the required asdf plugins (if not already installed):
  ```bash
  asdf plugin add nodejs
  asdf plugin add pnpm
  ```
* Install the correct tool versions:
  ```bash
  asdf install
  ```
* `pnpm install`

### Running

* `ember serve`
* Visit your app at [http://localhost:4200](http://localhost:4200).

### Running Tests

* `pnpm test` (Runs `ember try:each` to test your addon against multiple Ember versions)
* `ember test`
* `ember test --server`

### Security Auditing

This project uses PNPM for enhanced security and performance:

* `pnpm audit` - Check for security vulnerabilities
* `pnpm audit --fix` - Automatically fix resolvable vulnerabilities

See `BABEL_TRAVERSE_VULNERABILITY_GUIDE.md` for detailed security resolution strategies.

### Local Usage in Another Application

The demo app is useful for developing this addon, but it can often be helpful to consume your version of this addon in another application either to more easily develop your changes or to validate that your changes work as you expect. You can use your local version of `ember-hk-components` in another application that consumes it via PNPM's [link](https://pnpm.io/cli/link) command.

```sh
// in your ember-hk-components directory
> pnpm link --global

// in your consuming app directory
> pnpm link --global @heroku/ember-hk-components

// to put consuming app back on the release version
> pnpm unlink --global @heroku/ember-hk-components
> pnpm install @heroku/ember-hk-components
```

Now, when you make changes in your copy of `ember-hk-components` those changes will be reflected in the consuming application.

### Package Management

This project has migrated from Yarn to PNPM for:

- **Enhanced security** through stricter dependency resolution
- **Better performance** with content-addressable storage
- **Improved workspace support** for monorepo scenarios
- **Advanced resolution strategies** for vulnerability mitigation

All package management commands should use `pnpm` instead of `npm` or `yarn`.

### Recent Security Improvements

This project has recently undergone significant security hardening:

#### Vulnerability Resolution
- **Critical babel-traverse vulnerability** resolved via strategic package resolutions
- **High-severity vulnerabilities** in `rollup`, `json5`, `ansi-html` addressed
- **Transitive dependency vulnerabilities** mitigated through `@ladjs/consolidate` adoption

#### Dependency Updates
- **ember-a11y-testing** updated to `^5.2.1` for better compatibility
- **Package resolutions** strategically implemented for security without breaking changes
- **Comprehensive audit process** documented for future maintenance

#### Security Documentation
- `BABEL_TRAVERSE_VULNERABILITY_GUIDE.md` - Comprehensive guide for resolving babel-traverse vulnerabilities
- Detailed troubleshooting and implementation strategies
- Best practices for maintaining security in Ember CLI projects

For more details on security implementations, see the vulnerability guide and recent changelog entries.

### Releases

#### Notes

This library does its best to follow the principles of [Semantic Versioning](https://semver.org/).  Every effort should be made to ensure all non-major versions are released in a backwards compatible way.

#### Changelog

This project's changelog is generated using `lerna-changelog`.  You can find instructions on how to setup your local environment for this in [the project's Readme](https://github.com/lerna/lerna-changelog#github-token). Note that the Personal access token you use must be [SSO-enabled](https://help.github.com/en/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) for this to work.

`lerna-changelog` works off a system of labels defined in [this project's package.json](https://github.com/heroku/ember-hk-components/blob/9bdcf240e2294b48cac2e4f99ac5b706b7b17214/package.json#L61-L70).  Pull requests will be collated into the changelog based on which label has been applied to them.

#### Making a New Release

Once you are ready to make a new release follow these steps:

* Ensure all merged pull requests are labelled correctly as indicated in the Changelog section
* Create a new branch
* Update the version number in `package.json`
* Run `pnpm run changelog --from x.x.x` where `x.x.x` is the _last_ version of this library that was released.  This should generate changelog of changes _since_ that last release.
* Copy the output of that command into `CHANGELOG.md`
* Commit your changes and open a PR

Once the PR is approved and merged you can then tag your new version by running `git tag x.x.x` where `x.x.x` is the new version number. Push your tag to GitHub using `git push origin --tags`.

Publish your new version to npm with the command `pnpm publish` 🎉

_Note that you must have publish access to the @heroku npm organization to successfully publish_