import { Meta, ArgTypes, Story } from "@storybook/addon-docs/blocks";
import { Icon } from "./Icon";
import * as IconStories from "./Icon.stories";

<Meta of={IconStories} />

# Icon

Icon is a component for showing SVG icons provided by an icon library.

## Install

```bash
yarn add @simplybusiness/mobius
```

## Usage

```js
import { Icon } from "@simplybusiness/mobius";
```

## Adding New Icons

We use [Font Awesome Sharp Regular](https://fontawesome.com/search?o=r&s=regular&f=sharp) icons. To add a new icon:

### Option 1: GitHub Actions (recommended)

1. Go to [Actions → Add FontAwesome Icons](https://github.com/simplybusiness/mobius/actions/workflows/add-fontawesome-icons.yml)
2. Click **Run workflow**
3. Enter icon names (comma-separated), e.g. `chevron-down, arrow-up`
4. A PR will be created automatically

### Option 2: GitHub CLI

```bash
gh workflow run add-fontawesome-icons.yml -f icon_names="chevron-down, arrow-up"
```

## Examples

### All Icons

<Story of={IconStories.AllIcons} />

### Default

<Story of={IconStories.Default} />

{/* prettier-ignore */}
```jsx
import { Icon } from "@simplybusiness/mobius";
import { home } from "@simplybusiness/icons"

<Icon icon={home} />
```

### Spinning

<Story of={IconStories.Spinning} />

{/* prettier-ignore */}
```jsx
import { Icon } from "@simplybusiness/mobius";
import { loading } from "@simplybusiness/icons"

<Icon icon={loading} spin />
```

## Accessibility

Icons should have appropriate accessibility attributes to ensure proper screen reader support. The Icon component supports two main accessibility patterns:

### 1. Semantic Icons (with `title` prop)

Use the `title` prop for icons that convey important information or are the primary way information is communicated:

```jsx
// Icon appears alone and conveys meaning
<Icon icon={saveIcon} title="Save document" />

// Icon button where the icon is the primary content
<button>
  <Icon icon={closeIcon} title="Close dialog" />
</button>
```

### 2. Decorative Icons (with `aria-hidden="true"`)

Use `aria-hidden="true"` for decorative icons that accompany text or are purely visual enhancement:

```jsx
// Icon accompanies text that already conveys the meaning
<Button>
  <Icon icon={saveIcon} aria-hidden="true" />
  Save Document
</Button>

// Icon in error message (parent has role="alert")
<div role="alert">
  <Icon icon={errorIcon} aria-hidden="true" />
  <span>Error occurred while saving</span>
</div>
```

### When to Use Each Approach

**Use `title` prop when:**
- The icon is the primary way information is communicated
- The icon appears alone without accompanying text
- The icon conveys semantic meaning that isn't obvious from context

**Use `aria-hidden="true"` when:**
- The icon is decorative and accompanies text that already conveys the meaning
- The icon is in a container that already has appropriate ARIA roles (like `role="alert"`)
- The icon is purely visual enhancement

### Examples

#### ❌ Incorrect

```jsx
// Missing both title and aria-hidden
<Icon icon={saveIcon} />

// Decorative icon without aria-hidden
<Button>
  <Icon icon={saveIcon} />
  Save Document
</Button>
```

#### ✅ Correct

```jsx
// Semantic icon with meaningful title
<Icon icon={saveIcon} title="Save document" />

// Decorative icon hidden from screen readers
<Icon icon={saveIcon} aria-hidden="true" />

// Link with proper labeling
<Link aria-label="Go back to home" href="/">
  <Icon icon={arrowLeft} title="Go back" />
</Link>
```

## Props

<ArgTypes of={Icon} />

## Component HTML Structure and Class names

The following HTML is rendered for an Icon:

```html
<svg class="mobius-icon" focusable="false" role="img">
  <g ... />
</svg>
```
