# Luzmo Icons and Chart Icons Definitions

This repository contains the icons and chart icons definitions for Luzmo.

⚠️ **Alpha State**: This repository is in alpha state and the icons are not yet available for use. Expect breaking changes.

## Installation

Install the package along with its peer dependency:

```bash
npm install @luzmo/icons lit-html
```

## Icon Browser

The repository includes an `icon-viewer.html` file that provides a visual browser for all available icons.

### How to Use

First, ensure you have `live-server` installed globally:

```bash
npm install -g live-server
```

Then run the icon viewer with live reload:

```bash
npm run dev:viewer
```

This will start a local server and automatically open the icon browser in your browser. The viewer will auto-reload when icon definitions change.

### Features

- 🔍 **Search functionality** - Filter icons by name in real-time
- 📊 **Categorized display** - Icons organized into General Icons and Chart Icons
- 📋 **Click to copy** - Click any icon to copy its name to clipboard
- 📈 **Statistics** - View total icon count and visible icons after filtering
- 🎨 **Visual preview** - See all icons rendered at a glance

This viewer is particularly useful when selecting which icon to use in your project.

## Usage with Lit Element

The `@luzmo/icons` library is designed to work seamlessly with Lit elements. The `luzmoIcon()` helper function returns a `SVGTemplateResult` that can be used directly in Lit templates.

### Basic Example

```typescript
import { LitElement, html, css } from 'lit';
import { customElement } from 'lit/decorators.js';
import { luzmoIcon, luzmoFavico, luzmoSun } from '@luzmo/icons';

@customElement('my-component')
export class MyComponent extends LitElement {
  static styles = css`
    .icon {
      font-size: 24px;
      color: #667eea;
    }
  `;

  render() {
    return html`
      <div class="icon">
        ${luzmoIcon(luzmoFavico)}
      </div>
    `;
  }
}
```

### With Custom Options

```typescript
${luzmoIcon(luzmoSun, {
  className: 'custom-class',  // Additional CSS classes
  color: '#ff9800',           // Custom color (default: 'currentColor')
  prefix: 'my-icon'           // Custom prefix (default: 'luzmo-icon')
})}
```

### Dynamic Icons

```typescript
import { type IconDefinition } from '@luzmo/icons';

@customElement('chart-button')
export class ChartButton extends LitElement {
  @property({ type: Object })
  icon!: IconDefinition;

  render() {
    return html`
      <button>
        ${luzmoIcon(this.icon)}
        <span><slot></slot></span>
      </button>
    `;
  }
}
```

## Available Exports

### Icon Definitions
- General icons: `luzmoFavico`, `luzmoLogo`, `luzmoSun`, `luzmoMoon`, and more
- Chart/Item icons: `luzmoBarChart`, `luzmoLineChart`, `luzmoPieChart`, `luzmoAreaChart`, and more

### Helper Function
```typescript
luzmoIcon(definition: IconDefinition, options?: IconOptions): SVGTemplateResult
```

### TypeScript Interfaces
```typescript
interface IconDefinition {
  icon: [number, number, string | string[]] | [number, number, string | string[], string | string[]];
  name: string;
}

interface IconOptions {
  prefix?: string;
  className?: string;
  color?: string;
  verticalAlign?: string;
}
```

## Styling

Icons are rendered as SVG elements with the following default properties:
- **Height**: `1em` (scales with font-size)
- **Color**: `currentColor` (inherits from parent)
- **Vertical alignment**: Controlled via CSS variables `--luzmo-icon-vertical-align` or `--icon-vertical-align` (default: `-0.125em`)

### Custom Styling Example

```css
.icon {
  font-size: 48px;        /* Scale icon size */
  color: #667eea;         /* Set icon color */
  --luzmo-icon-vertical-align: -0.2em;  /* Adjust alignment */
}
```

## How to...

### Design an icon for this library
- Run `npm run build`
- Run `npm run serve:viewer`
- Visit http://localhost8080/icon-viewer.html
- Follow instructions in "Design Specs" section

### Add a new icon
- Follow guide in https://www.notion.so/cumulio/Adding-a-new-vizicon-to-the-visuals-2a9eac05171f80d281dde13c41c5d687

## License

Copyright © 2026 Luzmo. All rights reserved.

Lucero must be used according to the [Luzmo Terms of Service](https://www.luzmo.com/information-pages/terms-of-use). This license allows users with a current active Luzmo account to use Lucero.