npm package: @na-kit/ui
Description: A comprehensive UI Kit library built with Lit elements
Latest version: 1.8.0

# NA-Kit UI

> Enterprise-grade Web Components library built with Lit 3 & TypeScript — framework-agnostic, accessible, and tree-shakeable.

[![npm](https://img.shields.io/npm/v/@na-kit/ui)](https://www.npmjs.com/package/@na-kit/ui)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-1409%20passing-brightgreen)]()
[![a11y](https://img.shields.io/badge/WCAG-2.2%20AA-green)]()

## Highlights

- **74 components** — forms, data display, navigation, feedback, charts, marketing, and more
- **Framework-agnostic** — works with React, Vue, Angular, Svelte, or vanilla HTML
- **Accessible** — WCAG 2.2 AA compliant with full keyboard + screen reader support
- **Tree-shakeable** — import only the components you use (~147 KB gzipped full bundle)
- **Dark mode** — built-in light/dark theming via CSS custom properties
- **Enterprise utilities** — validation, i18n (8 locales + RTL), security, virtual scroll, data export
- **Type-safe** — full TypeScript definitions for every component

## Installation

```bash
npm install @na-kit/ui lit
```

### CDN

```html
<script type="module" src="https://unpkg.com/@na-kit/ui/dist/index.js"></script>
```

Or via jsDelivr:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@na-kit/ui/dist/index.js"></script>
```

## Quick Start

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <script type="module">
    import '@na-kit/ui';
  </script>
</head>
<body>
  <ui-theme-provider theme="light">
    <ui-container>
      <ui-typography variant="h1">Hello NA-Kit</ui-typography>
      <ui-button variant="primary">Get Started</ui-button>
    </ui-container>
  </ui-theme-provider>
</body>
</html>
```

### Individual Component Imports

Import only what you need for smaller bundles:

```js
import '@na-kit/ui/components/button/button.js';
import '@na-kit/ui/components/input/input.js';
```

## Components (74)

### Foundation
| Component | Tag | Description |
|-----------|-----|-------------|
| Button | `<ui-button>` | Primary, secondary, outlined, text, icon variants |
| Icon | `<ui-icon>` | SVG icon system with semantic/decorative modes |
| Typography | `<ui-typography>` | h1–h6, body, caption, overline, code |
| Theme Provider | `<ui-theme-provider>` | Light/dark mode with CSS custom properties |

### Layout
| Component | Tag | Description |
|-----------|-----|-------------|
| Container | `<ui-container>` | Responsive max-width container |
| Grid / Row / Col | `<ui-row>` `<ui-col>` | 12-column responsive grid |
| Stack / Flex | `<ui-stack>` `<ui-flex>` | Flexbox layout helpers |
| Card | `<ui-card>` | Content card with header/footer slots |
| Divider | `<ui-divider>` | Horizontal/vertical dividers |
| App Shell | `<ui-app-shell>` | Full page layout with header, sidebar, footer |

### Forms
| Component | Tag | Description |
|-----------|-----|-------------|
| Input | `<ui-input>` | Text, email, password, number, search, tel |
| Select | `<ui-select>` | Dropdown select with search and groups |
| Checkbox | `<ui-checkbox>` | Checkbox with indeterminate state |
| Radio | `<ui-radio>` | Radio button group |
| Switch | `<ui-switch>` | Toggle switch |
| Autocomplete | `<ui-autocomplete>` | Search with async suggestions |
| Multi-Select | `<ui-multi-select>` | Tag-based multi-selection |
| Date Picker | `<ui-datepicker>` | Calendar date picker with i18n |
| Color Picker | `<ui-colorpicker>` | HEX/RGB/HSL color picker |
| File Upload | `<ui-file-upload>` | Drag-and-drop with previews |
| Range Slider | `<ui-range-slider>` | Single and dual-thumb slider |
| Rating | `<ui-rating>` | Star/custom icon rating |
| Number Input | `<ui-number-input>` | Numeric stepper input |
| Rich Text Editor | `<ui-rich-text-editor>` | WYSIWYG with markdown and source view |

### Data Display
| Component | Tag | Description |
|-----------|-----|-------------|
| Table | `<ui-table>` | Sortable, resizable, expandable rows, sticky columns |
| Data Grid | `<ui-data-grid>` | Virtual scroll, inline edit, grouping, export |
| Avatar | `<ui-avatar>` | Image or initials with status |
| Avatar Group | `<ui-avatar-group>` | Stacked avatars with overflow |
| Badge | `<ui-badge>` | Status indicators and counters |
| Chip | `<ui-chip>` | Tags with remove action |
| List | `<ui-list>` | Ordered/unordered with icons |
| Timeline | `<ui-timeline>` | Vertical/horizontal timeline |
| Tree View | `<ui-tree-view>` | Hierarchical tree with checkboxes |
| Image | `<ui-image>` | Lazy-loading responsive image |
| Blockquote | `<ui-blockquote>` | Styled quotation |
| Code Block | `<ui-code-block>` | Syntax highlighted code |
| Kbd | `<ui-kbd>` | Keyboard shortcut display |

### Feedback & Overlays
| Component | Tag | Description |
|-----------|-----|-------------|
| Alert | `<ui-alert>` | Info, success, warning, error alerts |
| Modal | `<ui-modal>` | Dialog with focus trap |
| Drawer | `<ui-drawer>` | Slide-in side panel |
| Tooltip | `<ui-tooltip>` | Hover/focus tooltip |
| Popover | `<ui-popover>` | Rich content popover |
| Toast / Feedback | `<ui-feedback>` | Toast notifications with queue |
| Progress | `<ui-progress>` | Linear/circular progress |
| Spinner | `<ui-spinner>` | Loading spinner |
| Skeleton | `<ui-skeleton>` | Content placeholder loading |
| Empty State | `<ui-empty-state>` | Zero-data state |
| Announcement Bar | `<ui-announcement-bar>` | Dismissible site-wide banner |
| Cookie Consent | `<ui-cookie-consent>` | GDPR cookie consent banner |

### Navigation
| Component | Tag | Description |
|-----------|-----|-------------|
| Accordion | `<ui-accordion>` | Collapsible content panels |
| Breadcrumbs | `<ui-breadcrumbs>` | Navigation breadcrumb trail |
| Tabs | `<ui-tabs>` | Tabbed interface with overflow scroll |
| Stepper | `<ui-stepper>` | Step-by-step workflow |
| Pagination | `<ui-pagination>` | Page navigation |
| Menu | `<ui-menu>` | Dropdown and context menus |
| Dropdown | `<ui-dropdown>` | Trigger-based dropdown |
| Link | `<ui-link>` | Styled anchor with variants |
| Scroll to Top | `<ui-scroll-to-top>` | Floating scroll button |
| Command Palette | `<ui-command-palette>` | Cmd+K fuzzy search |

### Data Visualization
| Component | Tag | Description |
|-----------|-----|-------------|
| Chart | `<ui-chart>` | Line, bar, pie, doughnut, area, scatter |
| Gauge | `<ui-gauge>` | Radial gauge meter |
| Sparkline | `<ui-sparkline>` | Inline mini charts |
| Heatmap | `<ui-heatmap>` | Grid-based heatmap |

### Marketing & Website
| Component | Tag | Description |
|-----------|-----|-------------|
| Hero Section | `<ui-hero-section>` | Full-width hero banners |
| CTA Section | `<ui-cta-section>` | Call-to-action blocks |
| Carousel | `<ui-carousel>` | Image/content slider |
| Testimonial | `<ui-testimonial>` | Customer quotes and reviews |
| Pricing Table | `<ui-pricing-table>` | Plan comparison tables |
| Stats Counter | `<ui-stats-counter>` | Animated metric counters |
| FAQ | `<ui-faq>` | FAQ accordion with JSON-LD |
| Blog Card | `<ui-blog-card>` | Article preview cards |
| Social Share | `<ui-social-share>` | Social media share buttons |
| Countdown | `<ui-countdown>` | Event countdown timer |
| Logo Cloud | `<ui-logo-cloud>` | Partner/client logo marquee |
| Feature Grid | `<ui-feature-grid>` | Benefits grid with icons |
| Lightbox | `<ui-lightbox>` | Full-screen image gallery |
| Video Player | `<ui-video-player>` | Custom video controls |
| Image Comparison | `<ui-image-comparison>` | Before/after slider |

## Enterprise Utilities

```js
// Validators — 15+ built-in (email, url, phone, pattern, custom, async...)
import { validators, composeValidators } from '@na-kit/ui';

// i18n — 8 locales, RTL, date/number/currency formatting
import { LocaleProvider } from '@na-kit/ui';

// Security — XSS protection, CSP, HTML/URL sanitization
import { sanitizeHTML, generateCSP } from '@na-kit/ui';

// Data Export — CSV, Excel, JSON, clipboard, print
import { exportToCSV, exportToExcel } from '@na-kit/ui';

// Performance — debounce, throttle, memoize, virtual scroll
import { VirtualScrollController } from '@na-kit/ui';
```

## Theming

### CSS Custom Properties

```css
:root {
  --ui-color-primary: #6366f1;
  --ui-color-success: #10b981;
  --ui-color-danger: #ef4444;
  --ui-spacing-md: 16px;
  --ui-radius-md: 8px;
  --ui-font-family: system-ui, -apple-system, sans-serif;
}
```

### Dark Mode

```html
<ui-theme-provider theme="dark" persist-theme>
  <!-- Automatically applies dark theme -->
</ui-theme-provider>
```

### CSS Parts

All components expose `::part()` for deep styling:

```css
ui-button::part(button) { border-radius: 9999px; }
ui-input::part(input) { font-size: 18px; }
ui-card::part(card) { box-shadow: none; }
```

### Base Styles (Optional)

```js
import '@na-kit/ui/styles';          // All styles
import '@na-kit/ui/styles/reset.css'; // CSS reset only
import '@na-kit/ui/styles/dark-mode.css';
```

## Framework Integration

### React

```jsx
function App() {
  return (
    <ui-button variant="primary" onClick={() => alert('Clicked!')}>
      Click Me
    </ui-button>
  );
}
```

### Vue

```vue
<template>
  <ui-button variant="primary" @click="handleClick">
    Click Me
  </ui-button>
</template>

<script setup>
import '@na-kit/ui/components/button/button.js';
</script>
```

### Angular

```typescript
// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}
```

```html
<!-- component.html -->
<ui-button variant="primary" (click)="handleClick()">
  Click Me
</ui-button>
```

## Examples

### Login Form

```html
<ui-card elevated>
  <div slot="header">
    <ui-typography variant="h3">Sign In</ui-typography>
  </div>
  <ui-input label="Email" type="email" required></ui-input>
  <ui-input label="Password" type="password" required></ui-input>
  <ui-checkbox label="Remember me"></ui-checkbox>
  <div slot="footer">
    <ui-button variant="primary" full-width>Sign In</ui-button>
  </div>
</ui-card>
```

### Data Dashboard

```html
<ui-container>
  <ui-row>
    <ui-col span-md="3">
      <ui-stats-counter value="12847" label="Users" trend="up" trend-value="12%"></ui-stats-counter>
    </ui-col>
    <ui-col span-md="3">
      <ui-stats-counter value="94.2" suffix="%" label="Uptime"></ui-stats-counter>
    </ui-col>
  </ui-row>
  <ui-data-grid .columns=${columns} .data=${data} sortable filterable paginated></ui-data-grid>
</ui-container>
```

## Browser Support

- Chrome / Edge 90+
- Firefox 90+
- Safari 15+

## Development

```bash
npm install          # Install dependencies
npm run build        # Build the library
npm test             # Run 1409 tests
npm run test:coverage # Coverage report
npm run storybook    # Launch Storybook (788 stories)
npm run dev          # Build + dev server
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

[MIT](LICENSE)

---

Built with [Lit](https://lit.dev) ❤️