npm package: @junojs/ui
Description: Common UI components for JunoJS based on Tailwind CSS
Author: JunoJS Team
Latest version: 0.4.1

# @junojs/ui

A comprehensive, AI-native collection of UI components for **JunoJS**, powered by **Tailwind CSS 4.0**.

## ✨ Features

- **Framework-Native**: Built with JunoJS `@Component` decorators and Proxy-based reactivity.
- **Tailwind CSS 4.0**: Leverages the latest utility-first engine for styling and design tokens.
- **Shadow & Light DOM**: Supports both encapsulated and style-inheriting components.
- **Accessible**: Follows ARIA patterns for complex controls like Modals, Selects, and Popovers.
- **Ultra-Lightweight**: Minimal runtime overhead with native Web Component performance.

## 🚀 Installation

```bash
npm install @junojs/ui
```

## 🛠️ Usage

### 1. Style Setup

Import the base styles in your main entry file (e.g., `main.ts`):

```typescript
import "@junojs/ui/styles";
```

### 2. Component Registration

You can import components globally from the main bundle:

```typescript
import { ButtonComponent, InputComponent } from "@junojs/ui";
```

#### 🚀 Performance: Granular Imports

For better tree-shaking and faster development builds, we recommend importing components individually from their dedicated subpaths:

```typescript
import { ButtonComponent } from "@junojs/ui/button";
import { RowComponent, ColComponent } from "@junojs/ui/grid";
import { AlertComponent } from "@junojs/ui/alert";
```

> [!TIP]
> JunoJS components automatically call `bootstrap()` internally upon import. If you import a component subpath, it is immediately registered as a Custom Element in your application.

### 3. Basic Example

```html
<ui-card>
  <ui-container>
    <ui-row>
      <ui-col span="12">
        <h1 class="text-2xl font-bold">Welcome to JunoJS UI</h1>
        <ui-input label="Full Name" placeholder="John Doe"></ui-input>
        <ui-button variant="primary" @press="handleSubmit">Submit</ui-button>
      </ui-col>
    </ui-row>
  </ui-container>
</ui-card>
```

---

## 📦 Component Catalog

### 🏗️ Layout

Organize your application structure.

- **`ui-container`**: Max-width wrapper with responsive padding.
  - `fluid`: (boolean) Full width if true.
- **`ui-row`**: Flexbox container for columns.
  - `gap`: (number) Gap between columns.
- **`ui-col`**: Responsive column system.
  - `span`: (1-12) Column width.
  - `sm`, `md`, `lg`, `xl`: Responsive widths.

### 📝 Form Controls

Interactive elements for data entry.

- **`ui-button`**: Standard button control.
  - `variant`: `primary` | `secondary` | `outline` | `ghost`.
  - `disabled`: boolean.
- **`ui-input`**: High-level text input.
  - `label`, `placeholder`, `error`, `value`.
- **`ui-select`**: Single selection dropdown.
  - `label`, `options` (Array of {label, value}), `value`.
- **`ui-multi-select`**: Multi-selection with chips.
  - `values` (Array of selected values).
- **`ui-checkbox` & `ui-switch`**: Toggle controls.
  - `label`, `checked`.
- **`ui-date-picker`**: Calendar-based date selection.

### 📊 Data Display

Presenting information elegantly.

- **`ui-data-table`**: Advanced table with sorting, search, and pagination.
  - `data`, `columns`.
- **`ui-avatar`**: User profile representation.
  - `src`, `text`, `variant` (circle|square), `size`.
- **`ui-badge`**: Status markers.
  - `variant` (info|success|warning|danger).
- **`ui-card`**: Grouped content container.
- **`ui-calendar`**: Month-view picker component.

### 🧭 Navigation

Moving between views.

- **`ui-navbar`**: Main header navigation with mobile support.
- **`ui-menu`**: Flyout menus and context navigation.
- **`ui-link`**: Styled router-compatible links.
- **`ui-pagination`**: Controls for large data sets.

### 🔔 Feedback & Overlays

Dynamic UI states and notifications.

- **`ui-modal`**: Centered overlay for critical actions.
  - `open` (boolean).
- **`ui-popover`**: Contextual floating windows.
- **`ui-toast`**: Global notification system (requires `ui-toast-provider`).
- **`ui-alert`**: Inline feedback messages for long-standing states.
- **`ui-spinner` & `ui-skeleton`**: Beautiful loading states.

## 🎨 Styling with Tailwind CSS 4.0

The library uses Tailwind's **Atelier** design system by default. You can customize the theme by updating your `tailwind.config.ts`:

```javascript
/* your tailwind config */
export default {
  content: ["./node_modules/@junojs/ui/dist/**/*.js", "./src/**/*.{html,ts}"],
  theme: {
    extend: {
      colors: {
        brand: "#2563eb",
      },
    },
  },
};
```

## 📜 License

MIT © [JunoJS Team](https://junojs.example.com)