# @gkucmierz/bitcoin-logo

![NPM Version](https://img.shields.io/npm/v/@gkucmierz/bitcoin-logo)
![License](https://img.shields.io/npm/l/@gkucmierz/bitcoin-logo)

A premium, customizable, and interactive 3D-style Bitcoin logo component for Vue 3.

**Live Demo:** [https://bitcoin-logo.7u.pl/](https://bitcoin-logo.7u.pl/)

## 🚀 Features

- **3 Rotation Modes**: Auto-rotate, Interactive (drag & throw), and Controlled.
- **Physics-based Inertia**: Smooth deceleration in interactive mode.
- **Fully Customizable**: Adjust size, colors, stroke, animation speed, and more.
- **Lightweight**: Built with Vue 3 and SVG, no heavy 3D libraries.
- **Responsive**: Centers perfectly in any container.

## 📦 Installation

```bash
npm install @gkucmierz/bitcoin-logo
```

## 🛠 Usage

Import the component and its styles.

```vue
<script setup>
import BitcoinLogo from '@gkucmierz/bitcoin-logo'
import '@gkucmierz/bitcoin-logo/style.css' // Import CSS!
</script>

<template>
  <BitcoinLogo
    mode="interactive"
    :size="250"
    symbolColor="#f7931a"
  />
</template>
```

## 📖 API

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `String` | `'interactive'` | Operation mode: `'auto'`, `'interactive'`, or `'controlled'`. |
| `size` | `Number` | `200` | Size of the logo in pixels. |
| `symbolColor` | `String` | `'#fff'` | Color of the Bitcoin symbol (B) and stroke. |
| `strokeWidth` | `Number` | `5` | Thickness of the outer stroke. |
| `duration` | `Number` | `4` | **(Auto mode)** Duration of one full rotation in seconds. |
| `easing` | `String` | `'linear'` | **(Auto mode)** CSS easing function (e.g. `'ease-in-out'`). |
| `friction` | `Number` | `0.98` | **(Interactive mode)** Inertia friction factor (0.0 - 1.0). |
| `rotation` | `Number` | `0` | **(Controlled mode)** The rotation angle in degrees. Can be used with `v-model:rotation`. |

### Modes

#### 1. `interactive` (Default)
The user can drag the logo to rotate it. Releasing it with velocity triggers inertia.
- Emits `update:rotation` event with the current angle.
- `friction` prop controls how fast it stops spinning.

#### 2. `auto`
The logo rotates continuously using CSS animations.
- `duration` controls speed.
- `easing` controls animation curve.
- **Note:** Does not emit rotation events.
- **Easing Options:** `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`.


#### 3. `controlled`
The rotation is strictly determined by the `rotation` prop.
- Use this to link rotation to scroll position, mouse movement elsewhere, or other external state.

### Events

| Event | Payload | Description |
| --- | --- | --- |
| `update:rotation` | `Number` | Emitted when rotation changes in `'interactive'` mode. |

## 💡 Examples

### Interactive Mode (with v-model)

```vue
<script setup>
import { ref } from 'vue'
import BitcoinLogo from '@gkucmierz/bitcoin-logo'

const currentRotation = ref(0)
</script>

<template>
  <BitcoinLogo
    mode="interactive"
    v-model:rotation="currentRotation"
  />
  <p>Current Angle: {{ currentRotation.toFixed(0) }}°</p>
</template>
```

### Auto Mode

```vue
<template>
  <BitcoinLogo
    mode="auto"
    :duration="2"
    easing="ease-in-out"
  />
</template>
```

### Controlled Mode

```vue
<script setup>
import { ref } from 'vue'
import BitcoinLogo from '@gkucmierz/bitcoin-logo'

const angle = ref(0)
</script>

<template>
  <input type="range" v-model.number="angle" min="0" max="360" />
  <BitcoinLogo
    mode="controlled"
    :rotation="angle"
  />
</template>
```

---

## 📄 License

MIT