npm package: @swiftlyme/color-spotter
Description: > Pick colors from images, screen, URLs, hex input, or a full HSV picker — 100% browser-only. No signup. No server.
Latest version: 1.0.0

# 🎨 Color Spotter

> Pick colors from images, screen, URLs, hex input, or a full HSV picker — 100% browser-only. No signup. No server.

Color Spotter is a modern Angular-based color exploration tool featuring:

- 7 input methods
- Live color harmonies
- Tints & shades generation
- Full color format conversions
- Sidebar customization
- Sticky results panel
- Inline & popup HSV pickers
- Zero backend dependency

---

# 🖥 Application UI Overview

The app uses a **3-column layout**:

```
[ Sidebar ]   [ Center Panel ]   [ Results Panel ]
```

### 1️⃣ Sidebar (Method Selector)

- Dynamically rendered navigation items
- Toggle visibility of methods via **Customize sidebar drawer**
- Minimum 1 method always enforced
- Sticky positioning
- Privacy badge ("100% private — browser only")

Supported methods:

| ID              | Method                               |
| --------------- | ------------------------------------ |
| upload          | Upload image                         |
| paste           | Paste from clipboard                 |
| screen          | Screen EyeDropper                    |
| palette         | Preset swatches                      |
| url             | Load from image URL                  |
| hex             | Enter hex manually                   |
| picker          | Full HSV picker                      |
| method-selector | Embedded reusable selector component |

Users can toggle method visibility at runtime.

---

# 🎯 Center Panel – Input Methods

## Upload Image

- Click or drag & drop
- Supports JPG, PNG, GIF, WebP
- Click on image to sample pixel color

## Paste Image

- Uses Clipboard API
- Paste screenshot directly
- Click to sample

## Screen Picker

- Uses native `EyeDropper` API
- Supported:
  - Chrome 95+
  - Edge 95+
  - Opera 81+
- Graceful fallback message for unsupported browsers

## Preset Palette

- 24 default swatches
- Click to instantly generate:
  - Harmonies
  - Tints
  - Shades
  - Full color breakdown

## Image URL

- Accepts direct image links
- Loads into canvas
- Click to sample

## Hex Input

- Accepts 6-digit hex (with/without #)
- Live validation
- Quick color grid
- Generates:
  - HEX
  - RGB
  - HSL
  - HSV
  - CMYK
  - Harmonies
  - 5 Tints
  - 5 Shades

## Inline HSV Picker

Features:

- Saturation/Brightness gradient canvas
- Hue slider
- Opacity slider
- Live hex editing
- Copy button
- Harmonies update in real-time

---

# 📊 Results Panel

Sticky right panel shows:

## Primary Color

- Large swatch preview
- HEX
- RGB
- HSL
- HSV
- CMYK
- Click-to-copy rows

## Harmonies

- Complementary
- Analogous
- Triadic
- Additional variations
- Clickable swatches

## Tints

5 lighter variations

## Shades

5 darker variations

All swatches are interactive and feed back into the system.

---

# 🔐 Privacy

- 100% browser-based processing
- No server calls
- No image uploads
- No tracking
- All canvas operations client-side

Footer badge displayed in UI.

---

# 🧩 Reusable Package: `@swiftlyme/color-spotter`

The project also ships a reusable Angular component and utility toolkit.

---

# 📦 Installation

```bash
npm install @swiftlyme/color-spotter
```

---

# 🅰 Angular Drop-In Component

## Import

```typescript
import { ColorMethodSelectorComponent } from "@swiftlyme/color-spotter";

@NgModule({
  imports: [ColorMethodSelectorComponent],
})
export class AppModule {}
```

Or standalone:

```typescript
@Component({
  standalone: true,
  imports: [ColorMethodSelectorComponent]
})
```

---

## Usage

```html
<color-selection-method
  [initialColor]="'#e91e63'"
  [paletteColors]="myColors"
  (colorPicked)="onColor($event)"
>
</color-selection-method>
```

---

## Inputs

| Input         | Type     | Default     | Description          |
| ------------- | -------- | ----------- | -------------------- |
| initialColor  | string   | '#2889e9'   | Pre-seed color       |
| paletteColors | string[] | 24 defaults | Override palette tab |

---

## Output

| Output      | Type                 | Description        |
| ----------- | -------------------- | ------------------ |
| colorPicked | EventEmitter<string> | Emits selected hex |

---

# ⚙ Tab Management System

Each tab is defined as:

```ts
export interface TabItem {
  id: string;
  label: string;
  enabled: boolean;
}
```

Features:

- Toggle via gear dropdown
- Minimum 1 tab guard
- Auto-redirect if active tab disabled
- Outside click closes dropdown

Example:

```ts
toggleTab(tab: TabItem): void {
  const enabledCount = this.tabs.filter(t => t.enabled).length;
  if (tab.enabled && enabledCount <= 1) return;

  tab.enabled = !tab.enabled;

  if (!tab.enabled && this.activeMethod === tab.id) {
    const first = this.tabs.find(t => t.enabled);
    if (first) this.activeMethod = first.id;
  }
}
```

---

# 🛠 Utility Functions

Available utilities:

```ts
hexToRgb;
rgbToHex;
rgbToHsl;
rgbToHslValues;
rgbToHsvValues;
hsvToRgb;
hsvToHex;
rgbToCmyk;
getColorDetails;
generateColorHarmonies;
generateTints;
generateShades;
extractColorPalette;
extractColorPaletteFromFile;
getColorAtPixel;
getColorAtPixelFromFile;
isEyeDropperSupported;
pickColorFromScreen;
copyToClipboard;
isValidHex;
normaliseHex;
showColorPicker;
```

Example:

```ts
getColorDetails("#e91e63");
// {
//   hex: "#E91E63",
//   rgb: "rgb(233, 30, 99)",
//   hsl: "...",
//   hsv: "...",
//   cmyk: "..."
// }
```

---

# 🌐 Framework-Agnostic Popup Picker

Works without Angular:

```ts
import { showColorPicker } from "@swiftlyme/color-spotter";

const destroy = showColorPicker({
  initialColor: "#3b82f6",
  showHarmonies: true,
  onPick: (details) => {
    console.log(details.hex);
  },
});
```

---

# 🎯 Key Architecture Highlights

- Canvas-based color sampling
- HSV gradient rendering
- Sticky results wrapper
- Responsive grid layouts
- Fully component-driven
- No external UI libraries
- CSS animations & transitions
- Client-side palette extraction

---

# 🧠 Use Cases

- Design systems
- Admin dashboards
- Branding tools
- CMS color pickers
- Creative tools
- Theme generators
- Tag color selection
- SaaS white-label systems

---

## 📞 Support

For issues, questions, or feature requests, please visit (info@imminentideas.com)

## 🔗 Links

- [Documentation](https://swiftlyme.com/color-spotter/docs)
- [Live Demo](https://swiftlyme.com/color-spotter/demo)
- [NPM Package](https://www.npmjs.com/package/@swiftlyme/color-spotter)