npm package: @nassim_nabi/daris-ui
Description: Lightweight, dependency-free, framework-agnostic UI library with delightful animations and optional developer humor mode
Author: nassim nabi
Latest version: 1.0.0

# Daris UI

[![npm version](https://img.shields.io/npm/v/daris-ui.svg)](https://www.npmjs.com/package/daris-ui)
[![bundle size](https://img.shields.io/bundlephobia/minzip/daris-ui)](https://bundlephobia.com/package/daris-ui)
[![license](https://img.shields.io/npm/l/daris-ui.svg)](https://github.com/user/daris-ui/blob/main/LICENSE)

Lightweight, zero-dependency, framework-agnostic UI library with delightful animations and optional developer humor mode.

---

## Features

- **Modal** — Promise-based confirm dialogs with focus trap and backdrop
- **Toast / Snackbar** — Stacking notifications with 4 variants and positions
- **Alert Banner** — Inline dismissible alerts with animated collapse
- **Button Enhancer** — Ripple effects and loading states
- **Theme System** — CSS variables with light/dark presets and runtime switching
- **Humor Mode** — Optional witty messages and Easter eggs
- **Accessible** — ARIA roles, focus management, screen reader announcements
- **Tiny** — Under 15kb gzipped, zero dependencies
- **Ultra-Customizable** — Every visual property can be overridden via inline options
- **Playground** — Real-time visual configurator with live preview and code generation

## Playground

Try the interactive playground to visually configure every component and get copy-paste-ready code:

```bash
npm run dev
# Open http://localhost:5173/playground/
```

The playground features:
- Live preview with light/dark background toggle
- Controls for every customization option
- Generated code that shows only non-default options
- Copy-to-clipboard with one click

## Installation

```bash
npm install daris-ui
```

```bash
pnpm add daris-ui
```

```bash
yarn add daris-ui
```

## CDN Usage

```html
<link rel="stylesheet" href="https://unpkg.com/daris-ui/dist/style.css" />
<script src="https://unpkg.com/daris-ui/dist/daris-ui.iife.js"></script>
<script>
  const { modal, toast, alert, enhanceButtons, darisMood } = DarisUI;
</script>
```

## Quick Start

```ts
import { modal, toast, alert, enhanceButtons, setTheme, darisMood } from 'daris-ui';

// Enhance buttons with ripple effect
enhanceButtons();

// Show a toast
toast.success('Saved successfully!');
toast.error('Something went wrong');
toast.warning('Check your input', { duration: 5000 });
toast.info('Update available', { position: 'bottom-left' });

// Open a confirm modal
const result = await modal.open({
  title: 'Delete item?',
  content: 'This action cannot be undone.',
  confirmText: 'Delete',
  cancelText: 'Cancel',
});

if (result.confirmed) {
  // User confirmed
}

// Create an inline alert
alert.create('Changes saved!', document.getElementById('container'), {
  variant: 'success',
  dismissible: true,
});
```

## API Reference

### `toast`

| Method | Description |
|--------|-------------|
| `toast.success(message, options?)` | Green success notification |
| `toast.error(message, options?)` | Red error notification |
| `toast.warning(message, options?)` | Yellow warning notification |
| `toast.info(message, options?)` | Blue info notification |
| `toast.dismiss(element)` | Programmatically dismiss a toast |

**Options:**

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `duration` | `number` | `4000` | Auto-dismiss time in ms (0 = manual) |
| `position` | `string` | `'top-right'` | `top-right`, `top-left`, `top-center`, `bottom-right`, `bottom-left`, `bottom-center` |
| `closable` | `boolean` | `true` | Show close button |
| `title` | `string` | — | Bold title above message |
| `icon` | `string` | variant default | Custom icon (emoji/text). Empty string hides icon |
| `progressBar` | `boolean` | `false` | Show animated countdown bar |
| `animation` | `string` | `'slide'` | `slide`, `fade`, `bounce`, `none` |
| `actionLabel` | `string` | — | Text for action button |
| `onAction` | `function` | — | Action button callback |
| `html` | `string` | — | Custom HTML content |
| `backgroundColor` | `string` | — | Custom background color |
| `textColor` | `string` | — | Custom text color |
| `borderColor` | `string` | — | Custom border color |
| `borderWidth` | `string` | — | Border width (e.g. `'2px'`) |
| `borderRadius` | `string` | — | Border radius override |
| `borderStyle` | `string` | — | `solid`, `dashed`, `dotted`, `none` |
| `iconColor` | `string` | — | Custom icon background color |
| `shadow` | `string` | — | Custom box-shadow |
| `width` | `string` | — | Custom width |
| `fontFamily` | `string` | — | Font family override |
| `fontSize` | `string` | — | Font size override |
| `padding` | `string` | — | Custom padding |
| `gap` | `string` | — | Gap between elements |

### `modal`

| Method | Description |
|--------|-------------|
| `modal.open(options?)` | Open a modal, returns `Promise<{ confirmed: boolean }>` |
| `modal.close()` | Programmatically close the active modal |

**Options:**

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `title` | `string` | `''` | Modal title |
| `content` | `string` | `''` | Plain text body |
| `html` | `string` | `''` | HTML body (overrides content) |
| `confirmText` | `string` | `'OK'` | Confirm button label |
| `cancelText` | `string` | `'Cancel'` | Cancel button label |
| `showCancel` | `boolean` | `true` | Show cancel button |
| `closeOnBackdrop` | `boolean` | `true` | Close on backdrop click |
| `closeOnEsc` | `boolean` | `true` | Close on Escape key |
| `width` | `string` | `'480px'` | Max width of modal |
| `icon` | `string` | — | Icon in header |
| `headerAlign` | `string` | `'left'` | Header alignment |
| `footerAlign` | `string` | `'right'` | Footer alignment |
| `showFooter` | `boolean` | `true` | Show footer |
| `animation` | `string` | `'scale'` | `scale`, `fade`, `slideDown`, `slideUp`, `none` |
| `backgroundColor` | `string` | — | Modal surface color |
| `textColor` | `string` | — | Body text color |
| `borderColor` | `string` | — | Modal border color |
| `borderWidth` | `string` | — | Border width |
| `borderRadius` | `string` | — | Border radius |
| `borderStyle` | `string` | — | Border style |
| `overlayColor` | `string` | — | Backdrop color/opacity |
| `overlayBlur` | `string` | — | Backdrop blur (e.g. `'4px'`) |
| `shadow` | `string` | — | Box shadow |
| `padding` | `string` | — | Body padding |
| `fontFamily` | `string` | — | Font family |
| `fontSize` | `string` | — | Font size |
| `confirmColor` | `string` | — | Confirm button background |
| `cancelColor` | `string` | — | Cancel button background |
| `confirmTextColor` | `string` | — | Confirm button text color |
| `cancelTextColor` | `string` | — | Cancel button text color |
| `headerBorder` | `boolean` | `false` | Show border under header |
| `footerBorder` | `boolean` | `false` | Show border above footer |

### `alert`

| Method | Description |
|--------|-------------|
| `alert.create(message, container, options?)` | Create an alert in a container element |
| `alert.dismiss(element)` | Programmatically dismiss an alert |

**Options:**

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `variant` | `string` | `'info'` | `success`, `error`, `warning`, `info` |
| `dismissible` | `boolean` | `true` | Show dismiss button |
| `onDismiss` | `function` | — | Callback when dismissed |
| `title` | `string` | — | Bold title |
| `icon` | `string` | variant default | Custom icon |
| `action` | `object` | — | `{ label, onClick }` action button |
| `animation` | `string` | `'collapse'` | `collapse`, `fade`, `slide`, `none` |
| `duration` | `number` | `0` | Auto-dismiss after ms (0 = manual) |
| `progressBar` | `boolean` | `false` | Show countdown bar (requires duration) |
| `backgroundColor` | `string` | — | Custom background |
| `textColor` | `string` | — | Custom text color |
| `borderColor` | `string` | — | Custom border color |
| `borderWidth` | `string` | — | Border width |
| `borderRadius` | `string` | — | Border radius |
| `borderStyle` | `string` | — | Border style |
| `iconColor` | `string` | — | Custom icon color |
| `shadow` | `string` | — | Box shadow |
| `fontFamily` | `string` | — | Font family |
| `fontSize` | `string` | — | Font size |
| `padding` | `string` | — | Custom padding |

### `createButton(options?)`

Create a fully configured button element.

**Options:**

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `text` | `string` | `'Button'` | Button label |
| `variant` | `string` | `'primary'` | `primary`, `secondary`, `outline`, `ghost`, `danger` |
| `size` | `string` | `'md'` | `sm`, `md`, `lg` |
| `disabled` | `boolean` | `false` | Disabled state |
| `loading` | `boolean` | `false` | Loading spinner state |
| `onClick` | `function` | — | Click handler |
| `icon` | `string` | — | Icon text/emoji |
| `iconPosition` | `string` | `'left'` | `left`, `right` |
| `fullWidth` | `boolean` | `false` | Full width button |
| `backgroundColor` | `string` | — | Custom background |
| `textColor` | `string` | — | Custom text color |
| `hoverBackgroundColor` | `string` | — | Hover background color |
| `borderColor` | `string` | — | Border color |
| `borderWidth` | `string` | — | Border width |
| `borderRadius` | `string` | — | Border radius |
| `borderStyle` | `string` | — | Border style |
| `shadow` | `string` | — | Box shadow |
| `fontFamily` | `string` | — | Font family |
| `fontSize` | `string` | — | Font size |
| `padding` | `string` | — | Custom padding |

### `enhanceButtons(options?)`

Adds ripple effects to buttons with class `du-btn` or `data-du-btn` attribute.

### `setLoading(button, loading)`

Toggle loading spinner state on a button element.

## Advanced Customization

Override any visual property per-instance using inline style options:

```ts
toast.success('Custom styled!', {
  backgroundColor: '#1a1a2e',
  textColor: '#e0e0e0',
  borderColor: '#6366f1',
  borderWidth: '2px',
  borderRadius: '16px',
  shadow: '0 8px 32px rgba(99, 102, 241, 0.3)',
  fontFamily: '"Fira Code", monospace',
  progressBar: true,
  animation: 'bounce',
});

modal.open({
  title: 'Styled Modal',
  content: 'Fully customized appearance.',
  backgroundColor: '#0f172a',
  textColor: '#f1f5f9',
  overlayBlur: '4px',
  confirmColor: '#22c55e',
  animation: 'slideDown',
  headerBorder: true,
  footerBorder: true,
});
```

## Theming

Daris UI uses CSS custom properties for all visual styling.

### Presets

```ts
import { setPreset } from 'daris-ui';

setPreset('dark');  // Switch to dark theme
setPreset('light'); // Switch to light theme
```

### Custom Theme

```ts
import { setTheme } from 'daris-ui';

setTheme({
  primary: '#6366f1',
  primaryHover: '#4f46e5',
  radius: '12px',
  fontFamily: 'Inter, sans-serif',
});
```

All available theme properties:

| Property | CSS Variable | Default (light) |
|----------|-------------|-----------------|
| `primary` | `--du-primary` | `#6366f1` |
| `primaryHover` | `--du-primary-hover` | `#4f46e5` |
| `success` | `--du-success` | `#22c55e` |
| `error` | `--du-error` | `#ef4444` |
| `warning` | `--du-warning` | `#f59e0b` |
| `info` | `--du-info` | `#3b82f6` |
| `background` | `--du-bg` | `#ffffff` |
| `surface` | `--du-surface` | `#f8fafc` |
| `text` | `--du-text` | `#0f172a` |
| `radius` | `--du-radius` | `8px` |
| `fontFamily` | `--du-font` | system fonts |
| `animationDuration` | `--du-duration` | `200ms` |

## Humor Mode

```ts
import { darisMood } from 'daris-ui';

darisMood.enableHumor();  // Activate humor mode
darisMood.disableHumor(); // Deactivate

darisMood.isHumorEnabled(); // Check status
```

When enabled:
- Toasts include witty messages
- Playful console messages appear
- Trigger 10 rapid toasts for a hidden Easter egg

Humor mode is fully tree-shakeable and adds zero overhead when disabled.

## Accessibility

- All modals use `role="dialog"` with `aria-modal="true"` and `aria-labelledby`
- Focus is trapped within open modals and restored on close
- Toasts use `role="alert"` with `aria-atomic` and are announced via a live region
- Alert banners use `role="alert"`
- Buttons support `aria-busy` during loading state
- All interactive elements have visible `:focus-visible` outlines
- `prefers-reduced-motion` disables all animations

## Bundle Size

The full library is under **15kb gzipped**. Individual components are tree-shakeable — import only what you need.

## Browser Support

All modern browsers (Chrome, Firefox, Safari, Edge). ES2020 target.

## Roadmap

- [x] Interactive Playground / Emulator
- [x] Ultra-customizable components (inline style overrides)
- [x] Progress bars for toast and alert
- [x] Custom toast action buttons
- [x] Multiple animation variants
- [ ] Tooltip component
- [ ] Drawer / slide-over panel
- [ ] Plugin system
- [ ] Community themes

## Contributing

1. Fork the repository
2. Create a feature branch
3. Write TypeScript strict code with ARIA support
4. Test with screen readers
5. Submit a pull request

## License

MIT