# @tokens-studio/icons-webcomponents

A comprehensive, type-safe icon library as web components for use in any framework or vanilla JavaScript.

## Features

- ✅ **344+ icons** available as web components
- ✅ **TypeScript support** with full type definitions
- ✅ **Framework agnostic** - works with React, Vue, Angular, Svelte, or vanilla JS
- ✅ **Tree-shakeable** - import only what you need
- ✅ **AI-friendly** - comprehensive types and metadata for AI assistants
- ✅ **Customizable** - style with CSS custom properties

## Installation

```bash
npm install @tokens-studio/icons-webcomponents
```

## Usage

### Basic Usage

```html
<!-- Import the icon -->
<script type="module">
	import '@tokens-studio/icons-webcomponents/Plus';
</script>

<!-- Use it in your HTML -->
<icon-plus></icon-plus>
```

### TypeScript Usage

```typescript
// Import specific icon
import '@tokens-studio/icons-webcomponents/Plus';

// Or import all icons
import * as Icons from '@tokens-studio/icons-webcomponents';

// Use types for type-safe icon names
import type {
	IconName,
	IconComponentName,
} from '@tokens-studio/icons-webcomponents';

const iconTag: IconName = 'icon-plus';
const componentName: IconComponentName = 'Plus';
```

### React Usage

```tsx
import '@tokens-studio/icons-webcomponents/Plus';

function MyComponent() {
	return <icon-plus></icon-plus>;
}
```

### Vue Usage

```vue
<template>
	<icon-plus></icon-plus>
</template>

<script setup>
import '@tokens-studio/icons-webcomponents/Plus';
</script>
```

### Styling

Icons use `currentColor` for stroke/fill, so you can style them with CSS:

```css
icon-plus {
	color: #3b82f6;
	width: 32px;
	height: 32px;
}

/* Or use CSS custom properties */
icon-plus {
	--icon-width: 32px;
	--icon-height: 32px;
	color: #3b82f6;
}
```

## Type Safety

### Icon Name Types

```typescript
import type {
	IconName,
	IconComponentName,
} from '@tokens-studio/icons-webcomponents';

// Type-safe icon tag names
const tag: IconName = 'icon-plus'; // ✅ Valid
const invalid: IconName = 'icon-invalid'; // ❌ TypeScript error

// Type-safe component names
const component: IconComponentName = 'Plus'; // ✅ Valid
```

### Icon Maps

```typescript
import {
	iconTagToComponentMap,
	iconComponentToTagMap,
} from '@tokens-studio/icons-webcomponents';

// Convert tag name to component name
const componentName = iconTagToComponentMap['icon-plus']; // 'Plus'

// Convert component name to tag name
const tagName = iconComponentToTagMap['Plus']; // 'icon-plus'
```

## Icon Manifest

Access the complete icon manifest programmatically:

```typescript
import manifest from '@tokens-studio/icons-webcomponents/manifest';

console.log(manifest.total); // 344
console.log(manifest.icons); // Array of all icons with metadata
```

Each icon in the manifest includes:

- `name`: PascalCase component name (e.g., `"Plus"`)
- `tag`: Web component tag name (e.g., `"icon-plus"`)
- `keywords`: Search keywords for the icon
- `importPath`: Full import path
- `importStatement`: Ready-to-use import statement
- `componentImport`: Component import statement

## Available Icons

All icons are available with their kebab-case tag names. For example:

- `icon-plus` → `<icon-plus></icon-plus>`
- `icon-user` → `<icon-user></icon-user>`
- `icon-settings01` → `<icon-settings01></icon-settings01>`

Many icons also have "filled" variants:

- `icon-plus` (outline)
- `icon-plus-filled` (filled/solid)

## AI Assistant Support

This package is designed to be AI-friendly with:

1. **Comprehensive TypeScript types** - All icon names are typed
2. **Icon manifest** - JSON file with all icon metadata
3. **JSDoc comments** - Each icon component has documentation
4. **Type exports** - Easy to discover available icons programmatically

AI assistants can:

- Discover all available icons via types
- Get icon metadata from the manifest
- Understand icon usage through JSDoc
- Provide type-safe suggestions

## Development

### Building

```bash
npm run build
```

### Regenerating Icons

```bash
npm run regenerate
```

This will:

1. Clean existing icons
2. Convert SVG assets to React components (via SVGR)
3. Convert React components to web components
4. Generate type definitions and manifest

## License

[Your license here]