@loke/icons/README.md

A Loke icon library package for React applications.

# @loke/icons

A React icon library package inspired by lucide-react, providing tree-shakeable icon components.

## Features

- 🎨 107 carefully crafted icons
- 🌲 Tree-shakeable - only import what you need
- ⚡ Optimized for performance
- 📦 TypeScript support
- 🎯 Consistent API
- 🔧 Customizable via props

## Installation

```bash
bun add @loke/icons
```

## Usage

### Basic Usage

```tsx
import { Activity, Calendar, Users } from '@loke/icons';

function App() {
  return (
    <div>
      <Activity />
      <Calendar size={32} />
      <Users color="red" strokeWidth={1.5} />
    </div>
  );
}
```

### Available Props

All icons accept the following props:

- `size?: string | number` - Icon size (default: 24)
- `color?: string` - Icon color (default: "currentColor")
- `strokeWidth?: number` - Stroke width (default: 2)
- `absoluteStrokeWidth?: boolean` - Use absolute stroke width
- `className?: string` - Additional CSS classes
- Plus all standard SVG attributes

### Custom Icons

You can create custom icons using the `createLokeIcon` function:

```tsx
import { createLokeIcon } from '@loke/icons';
import type { IconNode } from '@loke/icons';

const customIconNode: IconNode = [
  ['path', { d: 'M10 10 L20 20' }],
  ['circle', { cx: '10', cy: '10', r: '5' }],
];

const CustomIcon = createLokeIcon('custom-icon', customIconNode);
```

### Using the Base Icon Component

```tsx
import { Icon } from '@loke/icons';
import type { IconNode } from '@loke/icons';

const iconNode: IconNode = [
  ['path', { d: 'M10 10 L20 20' }],
];

function MyComponent() {
  return <Icon iconNode={iconNode} size={24} />;
}
```

## Available Icons

All icons are exported in PascalCase:

- Activity
- AlarmClock
- AlertCircle
- AlertTriangle
- Archive
- ArrowDown
- ArrowLeft
- ArrowRight
- ArrowUp
- Award
- BarChart
- Building2
- Buildings
- Calculator
- Calendar
- CalendarClock
- Check
- CheckCircle
- ChevronDown
- ChevronLeft
- ChevronRight
- ChevronUp
- ChevronsDown
- ChevronsLeft
- ChevronsRight
- ChevronsUp
- ChevronsUpDown
- Circle
- CircleDollarSign
- CircleHelp
- CirclePlay
- CircleX
- Clock
- CloudUpload
- Code
- Copy
- CreditCard
- Dollar
- DollarSign
- Ellipsis
- ExternalLink
- Eye
- EyeOff
- FileText
- Filter
- Gift
- Globe
- GripVertical
- HelpCircle
- House
- Image
- Info
- Lightbulb
- Link
- List
- ListFilter
- Loader2
- LoaderCircle
- Lock
- Mail
- MapPin
- Megaphone
- Menu
- MessageSquare
- MessagesSquare
- Minus
- Moon
- Package
- Palette
- PanelLeft
- Pause
- Pencil
- Percent
- Phone
- PieChart
- Play
- Plus
- PoundSterling
- Puzzle
- RefreshCw
- Repeat
- RotateCcw
- Save
- Search
- Settings
- ShoppingBag
- SlidersHorizontal
- Smile
- SortAsc
- SortDesc
- Star
- Sun
- Tag
- Ticket
- Trash
- TrendingDown
- TrendingUp
- Unlink
- User
- UserCog
- Users
- Utensils
- Webhook
- Wifi
- WifiOff
- WrapText
- X

## Icon Metadata

The `src/meta/` directory contains metadata for each icon:

- **`.json` files**: Icon metadata including tags, categories, and aliases. These are used for icon search, filtering, documentation, and creating alternative import names. Each JSON file contains:
  ```json
  {
    "tags": [],       // Keywords for searching/filtering icons
    "categories": [], // Icon categories for organization
    "aliases": []     // Alternative names for importing this icon (optional)
  }
  ```

- **`.svg` files**: Original source SVG files in kebab-case format. These are the source files used during the build process to generate the React components.

These metadata files are kept in the repository for development purposes but are not included in the published npm package (only the compiled `dist` directory is published).

### Icon Aliases

Aliases allow you to import icons using alternative names. This is useful for:
- Providing backwards compatibility when renaming icons
- Offering multiple naming conventions (e.g., US vs UK spelling)
- Supporting common alternative names for the same icon

**Adding Aliases**

Add aliases to an icon's JSON metadata file:

```json
{
  "tags": ["search", "find"],
  "categories": ["ui"],
  "aliases": [
    {
      "name": "SearchIcon"
    },
    {
      "name": "Find",
      "deprecated": true,
      "deprecationReason": "Use Search instead",
      "toBeRemovedInVersion": "1.0.0"
    }
  ]
}
```

**Using Aliases**

Once defined, you can import icons using their alias names:

```tsx
import { SearchIcon, Find } from '@loke/icons';

// Both import the same 'search' icon
<SearchIcon />
<Find />  // Shows deprecation warning in IDE
```

**Deprecation**

Mark aliases as deprecated to guide users away from old names:
- `deprecated`: Set to `true` to mark the alias as deprecated
- `deprecationReason`: Optional message explaining why it's deprecated
- `toBeRemovedInVersion`: Optional version number when the alias will be removed

Deprecated aliases will show warnings in TypeScript-enabled editors via JSDoc comments.

## Development

### Generating Icons

```bash
bun run gen
```

Run this when adding or updating SVG icons. This will:
1. Read SVG files from `src/meta/`
2. Convert names from PascalCase to kebab-case
3. Generate TypeScript components in `src/icons/`
4. Create JSON metadata files (if they don't exist)
5. Generate the main index file and aliases
6. Format the generated code

The generated source files are committed to the repo.

### Building

```bash
bun run build
```

This compiles the package for distribution:
1. Clean the dist directory
2. Bundle JavaScript with Bun (ESM with "use client" directive)
3. Generate TypeScript declarations

### Type Checking

```bash
bun run typecheck
```

### Cleaning

```bash
bun run clean
```

This removes the `dist` directory.

## License

ISC