# EonUI Icons

`@eonui/icons` is the installable EonUI icon package. It merges multiple MIT-licensed icon families into one EonUI-facing token system, removes duplicate canonical names, and ships the result as transparent SVG files plus searchable metadata.

For the broader EonUI product surface, design references, and live ecosystem context, refer to `https://eonui.com`.

The current release contains:

- `12,351` unique SVG icons
- `18` EonUI purpose-led categories
- `12` bundled upstream MIT icon sources
- manifest and summary JSON for search, tooling, and docs

This package is designed for teams that want one large, consistent icon vocabulary for product UI, forms, dashboards, admin panels, SaaS apps, commerce flows, AI tooling, and documentation sites.

## Why This Package Exists

Teams often want icon breadth, but pulling raw icons from many libraries creates practical problems:

- different naming conventions
- duplicate concepts across libraries
- uneven category coverage
- hard-to-build search experiences
- messy license tracking

`@eonui/icons` solves that by turning many upstream sources into one consumer-friendly EonUI layer.

## What You Get

The package currently provides:

- transparent SVG assets grouped by category
- a stable `eon-*` token namespace
- deduplicated canonical names across upstream families
- `icons-manifest.json` for search, filtering, and docs
- `library-summary.json` for counts and diagnostics
- bundled MIT notices and third-party attribution files

The package stays framework-agnostic on purpose. It does not force Angular, React, or Vue component wrappers. Instead, it gives you the raw assets and metadata needed to build the integration style that fits your app.

## Current Source Coverage

The current catalog merges one preferred style from each of these MIT-compatible families:

- Tabler Icons
- Phosphor Icons
- Iconoir
- Heroicons
- Feather Icons
- Bootstrap Icons
- Eva Icons
- Radix Icons
- Primer Octicons
- Fluent UI System Icons
- Ant Design Icons
- Ionicons

Upstream attribution is preserved in the package, but the consumer-facing API remains centered on EonUI tokens.

## Who This Package Is For

This package is especially useful when you need:

- one shared icon layer across multiple projects
- direct SVG delivery without a runtime wrapper
- search and categorization for docs or picker tooling
- a large catalog for forms, product dashboards, and admin UI
- a stable naming system that stays independent of the upstream library brands

## Installation

```bash
npm install @eonui/icons
```

If you want to validate a local build from this workspace:

```bash
cd packages/icons
npm pack --dry-run
```

## Package Structure

Important files and folders:

- `eon-svg/`
  Final SVG assets grouped by EonUI category.
- `data/icons-manifest.json`
  Full metadata for every icon.
- `data/library-summary.json`
  Aggregate package statistics and source coverage.
- `src/index.js`
  ESM exports for library summary, categories, and source metadata.
- `src/index.d.ts`
  Type declarations for TypeScript consumers.
- `LICENSES/`
  Bundled copies of upstream MIT licenses.
- `THIRD_PARTY_NOTICES.md`
  Attribution and notice summary for the packaged sources.

## Token Naming

Every public icon is normalized into the `eon-*` namespace.

Examples:

- `eon-search`
- `eon-home`
- `eon-wallet`
- `eon-calendar`
- `eon-cloud`
- `eon-user`

This gives teams one stable vocabulary instead of tying product code to whatever the original upstream icon name happened to be.

## Categories

The current categories are:

- `communication`
- `office`
- `system`
- `commerce`
- `finance`
- `design`
- `development`
- `media`
- `people`
- `security`
- `maps`
- `arrows`
- `time`
- `weather`
- `education`
- `health`
- `games`
- `brands`

These categories are optimized for search, browsing, and docs tooling rather than being a rigid ontology.

## Quick Start Examples

### 1. Read library metadata

```js
import { iconLibrary, iconCategories, iconSources } from '@eonui/icons';

console.log(iconLibrary.packageName);
console.log(iconLibrary.totalIcons);
console.log(iconCategories.map((entry) => entry.slug));
console.log(iconSources.map((entry) => `${entry.label}: ${entry.keptCount}`));
```

Use this when:

- showing catalog statistics in docs
- checking release counts in CI
- exposing package diagnostics in internal tooling

### 2. Search the icon manifest

```js
import manifest from '@eonui/icons/data/icons-manifest.json' with { type: 'json' };

function searchIcons(query, category = 'all') {
  const normalized = query.trim().toLowerCase();

  return manifest.entries.filter((entry) => {
    if (category !== 'all' && entry.category !== category) {
      return false;
    }

    return entry.searchText.includes(normalized);
  });
}

console.log(searchIcons('wallet', 'finance').slice(0, 5));
```

Use this when:

- building an icon picker
- powering docs search
- generating filtered exports

### 3. Render icons in an Angular or Analog app

In file-based delivery, the simplest approach is often to use the public SVG path you control:

```ts
export class ToolbarComponent {
  readonly searchIcon = '/eonui/eon-icons/svg/system/eon-search.svg';
  readonly settingsIcon = '/eonui/eon-icons/svg/system/eon-settings.svg';
}
```

```html
<button type="button" class="toolbar-action">
  <img [src]="searchIcon" alt="" width="20" height="20" />
  <span>Search</span>
</button>

<button type="button" class="toolbar-action">
  <img [src]="settingsIcon" alt="" width="20" height="20" />
  <span>Settings</span>
</button>
```

Use this when:

- you want simple cacheable asset delivery
- you do not need a component wrapper yet
- you already host the public Eon icon bundle

### 4. Import a single SVG asset in a Vite-style build

If your build system supports asset URL imports:

```ts
import searchIconUrl from '@eonui/icons/svg/system/eon-search.svg?url';
import walletIconUrl from '@eonui/icons/svg/finance/eon-wallet.svg?url';

console.log(searchIconUrl, walletIconUrl);
```

Use this when:

- you want bundler-managed asset URLs
- you need only a small set of icons in a feature
- you are using Vite or another asset-aware build pipeline

### 5. Build category pages from the manifest

```js
import manifest from '@eonui/icons/data/icons-manifest.json' with { type: 'json' };

const grouped = manifest.entries.reduce((acc, entry) => {
  if (!acc[entry.category]) {
    acc[entry.category] = [];
  }

  acc[entry.category].push(entry);
  return acc;
}, {});

console.log(grouped.finance.slice(0, 10).map((entry) => entry.name));
```

Use this when:

- building docs pages by category
- generating "most used" or "team favorites" views
- creating internal browsing tools

### 6. Expose package summary in a service or dashboard

```js
import summary from '@eonui/icons/data/library-summary.json' with { type: 'json' };

const payload = {
  totalIcons: summary.totalIcons,
  totalCategories: summary.totalCategories,
  totalSources: summary.totalSources,
  generatedAt: summary.generatedAt,
};

console.log(payload);
```

Use this when:

- returning release metadata from an API
- building package health dashboards
- validating catalog size in automated checks

### 7. Read an icon path from manifest metadata

```js
import manifest from '@eonui/icons/data/icons-manifest.json' with { type: 'json' };

const search = manifest.entries.find((entry) => entry.name === 'eon-search');

console.log(search.publicPath);
console.log(search.svgPath);
```

Typical output:

```txt
/eonui/eon-icons/svg/system/eon-search.svg
./eon-svg/system/eon-search.svg
```

Use this when:

- you want a data-driven icon picker
- you need to store icon references in configuration
- you are bridging package metadata to a public asset host

## What The Package Can Power

This package is already suitable for:

- product sidebars and toolbars
- dashboard navigation
- settings pages and forms
- icon browsers and docs portals
- asset pickers for internal tools
- API-backed search metadata
- release dashboards that track coverage and growth

## Generation Workflow

Regenerate assets and metadata:

```bash
npm run generate
```

If you only want the package output and not the synced browser bundle:

```powershell
$env:EONUI_SYNC_PUBLIC = '0'
npm run generate
```

The generator currently does the following:

1. loads supported MIT icon sources
2. selects a preferred style or size when a source provides multiple variants
3. normalizes names into the Eon token namespace
4. removes duplicate canonical icons across sources
5. assigns EonUI categories and search metadata
6. writes package files and notice files
7. syncs a browser copy for the EonUI `/icons` page

## Current Limitations

There are a few deliberate tradeoffs in the current release:

- the catalog prefers one chosen style from each upstream source instead of publishing every possible weight or variant
- the package ships raw SVG assets rather than framework-specific components
- category assignment is metadata-driven and heuristic, not manually curated icon by icon

## Future Prospects

The strongest next steps for this package are:

- Angular, React, and Vue wrapper packages on top of the same token layer
- optional style channels such as filled or bold variants
- richer metadata such as accessibility hints or intent tags
- visual validation checks for malformed or off-center SVGs
- release automation for generate, validate, version, and publish

## License And Attribution

The EonUI wrapper layer is MIT-friendly and preserves upstream attribution for the included sources.

See:

- `THIRD_PARTY_NOTICES.md`
- `LICENSES/`
