npm package: @lazhus/kg-ui
Description: Modern, lightweight UI component library built with LitElement.
Author: Kolay Gelsin FE Team
Latest version: 0.9.10

# KG UI

Modern, lightweight UI component library built with LitElement.

## 🚀 Features

- ✨ **40+ Modern Components** - Tree, List, DataGrid, Modal, Avatar, and more
- 🎨 **Customizable Theming** - CSS variables for easy customization
- 🌓 **Dark Mode Support** - Built-in dark theme
- 📱 **Responsive** - Mobile-first design
- ⚡ **Lightweight** - Built with LitElement
- 🎯 **TypeScript Ready** - Full type support (Global & React/JSX)
- 📊 **Powerful DataGrid** - Server-side pagination, sorting, and custom rendering
- ♿ **Accessible** - ARIA compliant components

## 📦 Installation

```bash
npm install @lazhus/kg-ui
```

## 🎯 Quick Start

### 1. Import Components

You can import components individually or as a whole:

```javascript
// Import specific components
import '@lazhus/kg-ui/components/kg-button.js';
import '@lazhus/kg-ui/components/kg-input.js';

// OR import everything
import { kgbutton, kgloader, toast } from '@lazhus/kg-ui';
```

### 2. Import Styles

Add the CSS to your project:

```html
<link rel="stylesheet" href="node_modules/@lazhus/kg-ui/dist/kg-ui.css">
```

Or in your JavaScript/CSS:

```javascript
import '@lazhus/kg-ui/style.css';
```

### 3. Use in HTML

```html
<kg-button color="primary">Click Me</kg-button>
<kg-input label="Username" placeholder="Enter your name" error-text="This field is required"></kg-input>
<kg-avatar name="John Doe" color="secondary"></kg-avatar>
```

## 📝 Form Integration & Validation

KG UI components are built using `ElementInternals`, making them natively compatible with standard `<form>` elements.

### Form Submission
Buttons with `type="submit"` or `type="reset"` will trigger the corresponding form action:

```html
<form id="login-form">
  <kg-input name="email" type="email" label="Email" required></kg-input>
  <kg-input name="password" type="password" label="Password" required></kg-input>
  
  <kg-button type="submit" color="primary">Sign In</kg-button>
  <kg-button type="reset" basic>Clear</kg-button>
</form>
```

### Validation & Error Handling
All input-based components support the `error-text` property. Setting this property will display an error message below the component and apply error styling.

```html
<kg-input 
  label="Username" 
  error-text="Username already exists"
></kg-input>

<kg-select 
  label="Country" 
  error-text="Please select your country"
></kg-select>
```

## 🛠 Programmatic Access

Some components can be called via JavaScript for ease of use:

### Toast Notifications
```javascript
import { toast } from '@lazhus/kg-ui';

toast.success('Başarılı', 'İşlem başarıyla tamamlandı.');
toast.error('Hata', 'Bir sorun oluştu.');
```

### Loader Screen
```javascript
import { loader } from '@lazhus/kg-ui';

// Show loader
loader.show({ 
  text: 'Yükleniyor...', 
  glass: true 
});

// Hide loader
setTimeout(() => loader.hide(), 3000);
```

## 🎨 Theming

KG UI uses CSS variables for easy theming:

```css
:root {
  --kg-primary: #41ab34;
  --kg-secondary: #1367FF;
  --kg-tertiary: #FBB140;
  --kg-bg: #ffffff;
  --kg-text: #1a1a1a;
  /* ... more variables */
}
```

### Dark Mode

Enable dark mode by adding the `data-theme` attribute:

```javascript
document.documentElement.setAttribute('data-theme', 'dark');
```

## 📚 Components

### Foundation & General
- `kg-button` - Customizable button
- `kg-text` - Typography system
- `kg-card` - Content card
- `kg-avatar` - Profile image/initials
- `kg-tag` - Label/Badge
- `kg-divider` - Visual separator
- `kg-image` - Lazy loading image

### Navigation
- `kg-breadcrumbs` - Hierarchical crumbs
- `kg-tabs` - Tabbed interface
- `kg-stepper` - Step indicator

### Form Components
- `kg-input`, `kg-textarea`, `kg-select`
- `kg-checkbox`, `kg-radio`, `kg-switch`
- `kg-slider`, `kg-datepicker`, `kg-colorpicker`
- `kg-file-upload`

### Layout & Structure
- `kg-grid` / `kg-row` / `kg-column` - Grid system (w/ Gap & Align)
- `kg-accordion` - Collapsible sections
- `kg-modal` - Modal dialog
- `kg-drawer` - Side panel

### Feedback & Overlays
- `kg-toast` - Programmatic notification
- `kg-tooltip` - Contextual info balon
- `kg-loader` - Full-screen overlay
- `kg-spinner` - Loading indicator
- `kg-progress` - Progress bar
- `kg-skeleton` - Loading placeholder

### Data
- `kg-tree` - Hierarchical tree structure
- `kg-list` - Structured list rows
- `kg-datagrid` - Powerful data table

## 📄 License

MIT © Kolay Gelsin FE Team