# Z-UI - Modern Angular Component Library

A comprehensive, high-performance UI component library built with Angular 21+, featuring 40+ customizable components with dark mode, accessibility, and enterprise-ready features.

## Features

- **40+ Components** - Buttons, Inputs, Tables, Modals, Calendars, and more
- **Dark Mode** - Built-in theme support with 9 color themes
- **Accessible** - WCAG 2.1 compliant components
- **Responsive** - Mobile-first responsive design
- **High Performance** - OnPush change detection, virtual scrolling
- **Customizable** - CSS variables, class-variance-authority
- **Tree-shakable** - Import only what you need
- **Type-safe** - Full TypeScript support with strict mode
- **i18n Ready** - Built-in translation support

## Installation

```bash
pnpm add @shival99/z-ui
```

### Peer Dependencies

```bash
pnpm add @angular/cdk @ng-icons/core @ng-icons/lucide @ng-icons/iconsax \
  @tanstack/angular-table @shival99/angular-virtual \
  class-variance-authority clsx tailwind-merge \
  ngx-mask ngx-scrollbar @shival99/ngx-sonner ngxtension minisearch
```

### Optional Dependencies

```bash
pnpm add @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-placeholder @tiptap/extension-image @tiptap/extension-link @tiptap/extension-mention @tiptap/extension-underline @tiptap/extension-text-align @tiptap/markdown  # Rich Text Editor
pnpm add shiki dompurify                    # Syntax Highlighting
pnpm add echarts ngx-echarts                # Charts
pnpm add @ngx-translate/core @ngx-translate/http-loader  # i18n
pnpm add exceljs file-saver xlsx            # Excel Export
```

### Tailwind CSS v4 Setup

Z-UI requires Tailwind CSS v4. Install the dependencies:

```bash
pnpm add -D tailwindcss @tailwindcss/postcss postcss
```

Create `postcss.config.mjs` in your project root:

```javascript
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};
```

Update your `project.json` or `angular.json` styles:

```json
"styles": [
  "node_modules/@shival99/z-ui/assets/css/themes/green.css",
  "node_modules/@shival99/z-ui/assets/css/tailwind.css",
  "src/styles.scss"
]
```

Copy theme files to assets for lazy loading (optional):

```json
"assets": [
  {
    "glob": "*.css",
    "input": "node_modules/@shival99/z-ui/assets/css/themes",
    "output": "assets/css/themes"
  }
]
```

## Quick Start

### Import Components

```typescript
import { ZButtonComponent } from '@shival99/z-ui/components/z-button';
import { ZInputComponent } from '@shival99/z-ui/components/z-input';
import { ZTableComponent } from '@shival99/z-ui/components/z-table';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ZButtonComponent, ZInputComponent, ZTableComponent],
  template: `
    <z-button zVariant="primary">Click me</z-button>
    <z-input zLabel="Email" zPlaceholder="Enter email" />
  `,
})
export class AppComponent {}
```

### Configure Providers

```typescript
import { provideZTranslate } from '@shival99/z-ui/providers';
import { provideZNgxMask } from '@shival99/z-ui/providers';

export const appConfig: ApplicationConfig = {
  providers: [provideZTranslate({ defaultLang: 'vi', langPath: '/assets/i18n/' }), provideZNgxMask()],
};
```

## Components

| Category    | Components                                                       |
| ----------- | ---------------------------------------------------------------- |
| **Form**    | Input, Select, Checkbox, Radio, Switch, Calendar, Upload, Filter |
| **Data**    | Table, Pagination, Code, Editor, Timeline                        |
| **Overlay** | Modal, Drawer, Toast, Tooltip, Popover, Dropdown Menu            |
| **Layout**  | Accordion, Tabs, Menu, Breadcrumb, Skeleton                      |
| **Display** | Button, Icon, Loading                                            |

## Import Paths

```typescript
import { ZButtonComponent } from '@shival99/z-ui/components/z-button';
import { ZTableComponent } from '@shival99/z-ui/components/z-table';
import { ZModalService } from '@shival99/z-ui/components/z-modal';

import { ZThemeService, ZCacheService } from '@shival99/z-ui/services';
import { provideZTranslate } from '@shival99/z-ui/providers';
import { zTransform, zMergeClasses } from '@shival99/z-ui/utils';
import { ZSafeHtmlPipe } from '@shival99/z-ui/pipes';
import { Z_UI_TRANSLATIONS } from '@shival99/z-ui/i18n';
```

## Theming

Available themes: `green`, `orange`, `violet`, `neutral`, `zinc`, `slate`, `stone`, `gray`, `hospital`

```typescript
import { ZThemeService } from '@shival99/z-ui/services';

export class AppComponent {
  private themeService = inject(ZThemeService);

  ngOnInit() {
    this.themeService.setTheme('violet');
    this.themeService.toggleDarkMode(true);
  }
}
```

## CSS Variables

Z-UI uses CSS variables for customization. You can override these variables in your project's CSS to customize the look and feel.

### Font Variables

Override these in your `styles.css` or `styles.scss`:

```css
:root {
  --font-sans: 'Be Vietnam Pro', system-ui, -apple-system, sans-serif;
  --font-mono: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, 'Courier New', monospace;
}
```

Example - Using Inter font:

```css
:root {
  --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
}
```

### Theme Variables (Light Mode)

```css
:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0.031 264.539);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0.031 264.539);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0.031 264.539);
  --primary: oklch(0.422 0.095 166.913);
  --primary-foreground: oklch(0.982 0.018 166.913);
  --secondary: oklch(0.967 0.004 264.539);
  --secondary-foreground: oklch(0.209 0.021 264.539);
  --muted: oklch(0.967 0.004 264.539);
  --muted-foreground: oklch(0.556 0.024 264.539);
  --accent: oklch(0.967 0.004 264.539);
  --accent-foreground: oklch(0.209 0.021 264.539);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.985 0 0);
  --border: oklch(0.929 0.007 264.539);
  --input: oklch(0.929 0.007 264.539);
  --input-autofill: oklch(1 0 0);
  --ring: oklch(0.422 0.095 166.913);
  --chart-1: oklch(0.646 0.222 41.116);
  --chart-2: oklch(0.6 0.118 184.704);
  --chart-3: oklch(0.398 0.07 227.334);
  --chart-4: oklch(0.828 0.189 84.429);
  --chart-5: oklch(0.769 0.188 70.08);
  --sidebar: oklch(0.985 0.001 264.539);
  --sidebar-foreground: oklch(0.145 0.031 264.539);
  --sidebar-primary: oklch(0.422 0.095 166.913);
  --sidebar-primary-foreground: oklch(0.982 0.018 166.913);
  --sidebar-accent: oklch(0.967 0.004 264.539);
  --sidebar-accent-foreground: oklch(0.209 0.021 264.539);
  --sidebar-border: oklch(0.929 0.007 264.539);
  --sidebar-ring: oklch(0.422 0.095 166.913);
}
```

### Theme Variables (Dark Mode)

```css
.dark {
  --background: oklch(0.145 0.031 264.539);
  --foreground: oklch(0.985 0.001 264.539);
  --card: oklch(0.209 0.021 264.539);
  --card-foreground: oklch(0.985 0.001 264.539);
  --popover: oklch(0.209 0.021 264.539);
  --popover-foreground: oklch(0.985 0.001 264.539);
  --primary: oklch(0.696 0.17 162.48);
  --primary-foreground: oklch(0.209 0.021 264.539);
  --secondary: oklch(0.268 0.019 264.539);
  --secondary-foreground: oklch(0.985 0.001 264.539);
  --muted: oklch(0.268 0.019 264.539);
  --muted-foreground: oklch(0.708 0.019 264.539);
  --accent: oklch(0.268 0.019 264.539);
  --accent-foreground: oklch(0.985 0.001 264.539);
  --destructive: oklch(0.704 0.191 22.216);
  --destructive-foreground: oklch(0.985 0 0);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --input-autofill: oklch(0.19 0 0);
  --ring: oklch(0.527 0.154 150.069);
  --chart-1: oklch(0.488 0.243 264.376);
  --chart-2: oklch(0.696 0.17 162.48);
  --chart-3: oklch(0.769 0.188 70.08);
  --chart-4: oklch(0.627 0.265 303.9);
  --chart-5: oklch(0.645 0.246 16.439);
  --sidebar: oklch(0.209 0.021 264.539);
  --sidebar-foreground: oklch(0.985 0.001 264.539);
  --sidebar-primary: oklch(0.696 0.17 162.48);
  --sidebar-primary-foreground: oklch(0.209 0.021 264.539);
  --sidebar-accent: oklch(0.268 0.019 264.539);
  --sidebar-accent-foreground: oklch(0.985 0.001 264.539);
  --sidebar-border: oklch(1 0 0 / 10%);
  --sidebar-ring: oklch(0.527 0.154 150.069);
}
```

### Scrollbar Variables

```css
:root {
  --scrollbar-track-color: transparent;
  --scrollbar-track-shape: 5px;
  --scrollbar-track-thickness: 7px;
  --scrollbar-thumb-color: #d1d5db;
  --scrollbar-thumb-hover-color: #9ca3af;
  --scrollbar-thumb-shape: 5px;
  --scrollbar-thumb-min-size: 40;
  --scrollbar-hover-opacity-transition-leave-duration: 0.3s;
  --scrollbar-hover-opacity-transition-leave-delay: 0.5s;
}

.dark {
  --scrollbar-thumb-color: #4b5563;
  --scrollbar-thumb-hover-color: #6b7280;
}
```

### Example: Custom Override

Create a custom theme by overriding variables in your project:

```css
/* styles.css */
:root {
  /* Custom font */
  --font-sans: 'Roboto', system-ui, sans-serif;

  /* Custom primary color */
  --primary: oklch(0.6 0.2 240);
  --primary-foreground: oklch(1 0 0);

  /* Custom border radius */
  --radius: 0.5rem;
}

.dark {
  /* Dark mode primary color */
  --primary: oklch(0.7 0.2 240);
}
```

## License

MIT © [VuBoi](https://github.com/vuboi)