npm package: @heroku/ember-malibu-icon
Description: Ember Malibu Icons
Author: Heroku
Latest version: 4.0.0

# Ember Malibu Icon

This Ember addon injects the [Malibu](https://hk-malibu.herokuapp.com/) svg sprite into your Ember application and provides a helper to insert icons into your templates. You can explore how this helper works in this addon's [demo app and documentation](https://ember-malibu-icon.herokuapp.com/).

_Note that it will be helpful if you also use [Purple 3](https://purple3.herokuapp.com/) for styling_

## Installation

`ember install --save @heroku/ember-malibu-icon`

## Configuration

### Malibu version

By default the addon loads the `latest` Malibu sprite. To pin a specific version, set `ENV['ember-malibu-icon']` in your app's `config/environment.js`:

```js
ENV['ember-malibu-icon'] = {
  malibuVersion: '1.3.0',
};
```

### Mirage JS

If your app uses [Mirage JS](https://miragejs.com/) for API mocking, you'll need to configure it to allow requests to the Malibu CDN. Add this to your `mirage/config.js`:

```javascript
export default function () {
  // ... your existing routes

  // Allow Malibu sprite requests to pass through to CDN
  this.passthrough('https://www.herokucdn.com/malibu/**');
}
```

## Ember Template Lint Rules

Ember Malibu Icon also comes with a bunch of handy [Ember Template Lint](https://github.com/ember-template-lint/ember-template-lint) rules to help remind you to declare accessibility options when possible.

To use these lint rules in your app, add the following to your `.template-lintrc.js` file:

```javascript
module.exports = {
  extends: ['recommended', '@heroku/ember-malibu-icon:recommended'],
  plugins: [
    require('@heroku/ember-malibu-icon/lib/ember-template-lint-plugin'),
  ],
};
```

The documentation for each rule can be found in the [docs/rules directory](/docs/rules) folder of this project.

## Compatibility

- Ember.js 3.28 or above (see `versionCompatibility` in package.json)
- Works with both Embroider and classic Ember builds
- Node.js 20 or above

## Usage

### From a Handlebars (.hbs) file

#### Accessibility

**Accessibility** When rendering `MalibuIcon`, you must declare the icon as either:

- **informational**: Pass a non-empty string to `@title` argument. This will read the text to the screenreader instead of being announced as "Image".
- **decorative**: Pass `aria-hidden="true"` to the component. This will hide the icon from assistive technology. This should only be used for icons that don't convey additional meaning and are being used for aesthetic/design reasons.

#### Informational Usage Example

Use this when when you want text to be announced to the screenreader. This is most common when you have icons that are used for buttons or links but lack text rendered next to the icon to describe it.

```handlebars
<MalibuIcon
  @title='Add Buildpack {{buildpackName}}'
  @size='28'
  @iconClass='gradient-dark-gray'
  @name='app-28'
/>
```

For example:

![Image showing a list of domains. Each row has a pencil icon which is rendered by Malibu. There is no matching text which is an example of a use case for passing the `@title` argument.](/docs/images/informational.png)

Given this screenshot, note the pencil icon. There is no text next to it to describe its intended purpose to the screenreader (in this case, "Edit"). `@title="Edit {{domain}}"` would be an improvement in this scenario.

#### Decorative Usage

Use this when the icon does not convey additional meaning. There should be visual text accompanying the icon. **Never use this when only the icon is rendered**.

![Image showing the text "GitHub" next to an SVG icon of the GitHub logo.](/docs/images/decorative.png)

In this example, the GitHub logo is "decorative" because it does not convey additional meaning not already presented to the user via the "GitHub" text next to it.

```handlebars
<MalibuIcon
  @size='28'
  @iconClass='gradient-dark-gray'
  @name='app-28'
  aria-hidden='true'
/>
```

### From a javascript file (not recommended/deprecated)

```js
import { malibuIcon } from '@heroku/ember-malibu-icon/helpers/malibu-icon';
malibuIcon({
  name: 'app-16',
  size: 16,
  iconClass: 'v-mid gradient-purple',
  title='Optional Title'
})
```

## Development

- `git clone https://github.com/heroku/ember-malibu-icon`
- `cd ember-malibu-icon`
- `pnpm install`

## Running

- `pnpm start`
- Visit your app at [http://localhost:4200](http://localhost:4200).

## Running Tests

- `pnpm test` (Runs the demo app build and Ember tests via Testem)
- `pnpm test:ember-template-lint` (Runs the template lint rule tests)

## Building

- `pnpm build` (Builds the addon with Rollup; also runs automatically on `prepare` and `prepack`)

For more information on using ember-cli, visit [https://ember-cli.com/](https://ember-cli.com/).

## 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.

### Making a New Release

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

- Create a new branch
- Update the version number in `package.json`
- Commit your changes and open a PR
- When the PR is merged, create a GitHub release
  - Releases -> Draft a new release
  - Select tag -> Create a new tag
  - Name the tag the same as the version e.g. v4.1.3 (this should match what's in the package.json)
  - Click Generate release notes
  - Save draft
  - Review the draft then Publish release

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

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