npm package: @sekiui/elements
Description: Modern, accessible Web Components with shadcn/ui-inspired design
Latest version: 0.0.82

# SekiUI Components

Modern, accessible Web Components library built with Stencil.js, inspired by shadcn/ui design principles.

## Features

- 🎨 **Modern Design**: Clean, minimal components following shadcn/ui aesthetic
- ♿ **Accessibility First**: WCAG 2.1 Level AA compliant
- 🌗 **Dark Mode**: First-class dark mode support via CSS custom properties
- 📦 **Framework Agnostic**: Works with React, Vue, Angular, or vanilla JavaScript
- 🎯 **TypeScript**: Full TypeScript definitions included
- 🎭 **Storybook**: Interactive component documentation
- 🔧 **Tree-shakeable**: Import only what you need

## Getting Started

The fastest way to set up SekiUI in any project:

```bash
npx @sekiui/cli init
```

This interactive wizard will:
- Auto-detect your framework (React, Vue, Angular, or Vanilla HTML)
- Let you pick a color theme: **Neutral · Zinc · Slate · Rose · Blue · Violet**
- Set a border radius style: **None · Default · Rounded · Pill**
- Inject CSS design tokens into your global stylesheet
- Wire up `defineCustomElements()` (or `CUSTOM_ELEMENTS_SCHEMA` for Angular)
- Create a sample component to verify everything works

Then get usage snippets for any component:

```bash
npx @sekiui/cli add button
npx @sekiui/cli add select
npx @sekiui/cli add tooltip --framework vue
npx @sekiui/cli add badge --output src/snippets/badge.txt
```

Each `add` output includes:
1. The import/loader snippet for your framework
2. CSS custom properties you can override
3. A minimal, copy-ready usage example

**Available components:** `button` · `input` · `select` · `dialog` · `badge` · `card` · `alert` · `tooltip` · `dropdown-menu` · `tabs`

---

## Components

### Available Components

- **Button** (`seki-button`) - Versatile button component with multiple variants (primary, secondary, outline, ghost, destructive, link) and sizes
- **Input** (`seki-input`) - Fully accessible form input with support for all HTML input types, validation, and error states

[View all components in Storybook →](https://sekiui-storybook.pages.dev)

## Installation

### Via npm (Recommended)

```bash
npm install @sekiui/elements
```

### Via CDN (No Build Required)

For quick prototyping or projects without a build system, you can load SekiUI directly from a CDN.

**Latest Stable Version (unpkg):**
```html
<script type="module" src="https://unpkg.com/@sekiui/elements@latest/dist/sekiui/sekiui.esm.js"></script>
```

**Latest Stable Version (jsDelivr):**
```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@sekiui/elements@latest/dist/sekiui/sekiui.esm.js"></script>
```

**Specific Version (recommended for production):**
```html
<!-- Replace 0.0.41 with your desired version -->
<script type="module" src="https://unpkg.com/@sekiui/elements@0.0.41/dist/sekiui/sekiui.esm.js"></script>
```

**Complete Example:**
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>SekiUI via CDN</title>
</head>
<body>
  <h1>SekiUI Components</h1>

  <!-- Use components directly -->
  <seki-button variant="primary">Click me</seki-button>
  <seki-button variant="secondary">Secondary</seki-button>
  <seki-input type="email" placeholder="you@example.com"></seki-input>

  <!-- Load SekiUI Web Components -->
  <script type="module" src="https://unpkg.com/@sekiui/elements@latest/dist/sekiui/sekiui.esm.js"></script>
</body>
</html>
```

**CDN Notes:**
- ✅ HTTPS enabled on all CDN URLs
- ✅ CORS headers configured for cross-origin requests
- ✅ Versioned URLs cached long-term (immutable)
- ✅ Latest URLs cached short-term (updates automatically)
- ✅ Design tokens are integrated within components (no separate CSS file needed)
- ⚠️ For production, use versioned URLs to ensure consistency

## Usage

SekiUI supports both **lazy-loading all components** (recommended) and **importing individual components** for maximum bundle optimization.

### Import Strategy

**Option 1: Lazy-Load All Components (Recommended)**
- Components are automatically loaded on-demand when used
- Best developer experience with minimal setup
- Small initial bundle (~5-10KB), components load as needed

**Option 2: Import Individual Components**
- Maximum tree-shaking and bundle optimization
- Import only specific components you use
- Best for performance-critical applications

---

### Vanilla JavaScript / HTML

#### Option 1: Using CDN (Recommended for Quick Start)

All components are automatically registered when you load the CDN bundle. No additional setup required.

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <!-- Use components directly -->
  <seki-button variant="primary">Click me</seki-button>
  <seki-input type="email" placeholder="you@example.com"></seki-input>

  <!-- Load from CDN - components auto-register -->
  <script type="module" src="https://unpkg.com/@sekiui/elements@latest/dist/sekiui/sekiui.esm.js"></script>
</body>
</html>
```

#### Option 2: Using npm with Lazy-Loading

Components are loaded on-demand when used in the DOM. Requires calling `defineCustomElements()`.

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
  <!-- Components load automatically when rendered -->
  <seki-button variant="primary">Click me</seki-button>
  <seki-input type="email" placeholder="you@example.com"></seki-input>

  <!-- Loader enables lazy-loading -->
  <script type="module">
    import { defineCustomElements } from './node_modules/@sekiui/elements/loader/index.js';
    defineCustomElements();
  </script>
</body>
</html>
```

**Or with a bundler (Vite, Webpack, etc.):**

```js
// main.js - Components lazy-load on-demand
import { defineCustomElements } from '@sekiui/elements/loader';
defineCustomElements();
```

#### Option 3: Import Individual Components

For maximum tree-shaking, import only specific components you need.

```html
<!DOCTYPE html>
<html>
<body>
  <seki-button variant="primary">Click me</seki-button>

  <script type="module">
    // Only imports button component (~3-5KB)
    import { defineCustomElement } from './node_modules/@sekiui/elements/dist/components/seki-button.js';
    defineCustomElement();
  </script>
</body>
</html>
```

**Or with a bundler:**

```js
// Only button component is bundled
import { defineCustomElement } from '@sekiui/elements/dist/components/seki-button.js';
defineCustomElement();
```

---

### React

#### Using All Components (Lazy-Loaded)

```jsx
// App.jsx
import { SekiButton, SekiInput } from '@sekiui/elements/react';

function App() {
  return (
    <>
      <SekiButton variant="primary">Click me</SekiButton>
      <SekiInput type="email" placeholder="you@example.com" />
    </>
  );
}
```

#### Using Individual Components

```jsx
// Import only button wrapper
import { SekiButton } from '@sekiui/elements/react';

function App() {
  return <SekiButton variant="primary">Click me</SekiButton>;
}
```

**Or use the native custom element directly:**

```jsx
import { defineCustomElement } from '@sekiui/elements/dist/components/seki-button.js';

// Register once at app startup
defineCustomElement();

function App() {
  return <seki-button variant="primary">Click me</seki-button>;
}
```

---

### Vue 3

#### Using All Components (Lazy-Loaded)

**Global Registration (Recommended):**

```js
// main.js
import { createApp } from 'vue';
import App from './App.vue';
import { defineCustomElements } from '@sekiui/elements/loader';

// Components lazy-load on-demand
defineCustomElements();

createApp(App).mount('#app');
```

```vue
<!-- Any component can now use SekiUI -->
<template>
  <seki-button variant="primary">Click me</seki-button>
  <seki-input type="email" placeholder="you@example.com"></seki-input>
</template>
```

**Component-level Registration:**

```vue
<template>
  <seki-button variant="primary">Click me</seki-button>
</template>

<script setup>
import { defineCustomElements } from '@sekiui/elements/loader';
defineCustomElements();
</script>
```

#### Using Individual Components

```vue
<template>
  <seki-button variant="primary">Click me</seki-button>
</template>

<script setup>
// Only imports button component
import { defineCustomElement } from '@sekiui/elements/dist/components/seki-button.js';
defineCustomElement();
</script>
```

**Vue 3 Config (Optional):**

To prevent Vue warnings about unknown custom elements, add to `vite.config.js`:

```js
export default {
  vue: {
    template: {
      compilerOptions: {
        isCustomElement: (tag) => tag.startsWith('seki-')
      }
    }
  }
}
```

---

### Angular

#### Using All Components (Lazy-Loaded)

```typescript
// app.module.ts
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { defineCustomElements } from '@sekiui/elements/loader';

// Register all components (lazy-loaded)
defineCustomElements();

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  imports: [BrowserModule],
  // ...
})
export class AppModule { }
```

```html
<!-- app.component.html -->
<seki-button variant="primary">Click me</seki-button>
<seki-input type="email" placeholder="you@example.com"></seki-input>
```

#### Using Individual Components

```typescript
// app.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { defineCustomElement } from '@sekiui/elements/dist/components/seki-button.js';

// Only imports button component
defineCustomElement();

@Component({
  selector: 'app-root',
  template: '<seki-button variant="primary">Click me</seki-button>',
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppComponent {}
```

---

### Bundle Size Comparison

| Import Method | Initial Bundle | Notes |
|--------------|----------------|-------|
| **CDN (lazy-loaded)** | ~5-10KB | Components download on first use |
| **Loader (all components)** | ~5-10KB | Lazy-loads components as needed |
| **Individual component** | ~3-5KB | Only `seki-button` + shared runtime |
| **Multiple individual** | Varies | Each component ~2-4KB + shared runtime |

**Recommendation:** Use the loader approach for most projects. It provides excellent performance through automatic lazy-loading while maintaining the best developer experience.

## License

MIT © SekiUI Team