sigpro-ui/docs/quick.md

# SigPro-UI Quick Reference

**Version:** daisyUI v5 + Tailwind v4 Plugin  
**Status:** Active / WIP

> **Prerequisites:** Tailwind CSS v4+ and DaisyUI v5+ installed.

## Global Initialization

```javascript
import { UI } from 'sigpro-ui';

// Injects all components into window and sets default language
UI('en'); // 'es' or 'en'

// All components (Button, Input, Table, Toast, etc.) are now globally available.
```

---

## Core Components

| Component | Purpose | Basic Example |
| :--- | :--- | :--- |
| **Button** | Styled button with DaisyUI | `Button({ class: "btn-primary" }, "Submit")` |
| **Input** | Reactive text field with floating label | `Input({ label: "Name", value: $name })` |
| **Select** | Dropdown selection menu | `Select({ options: ["Admin", "User"], value: $role })` |
| **Checkbox** | Binary toggle (boolean) | `Checkbox({ label: "Active", checked: $isActive })` |
| **Table** | Data grid with column rendering | `Table({ items: $data, columns: [...] })` |
| **Modal** | Overlay dialog controlled by a Signal | `Modal({ open: $show, title: "Alert" }, "Message")` |
| **Badge** | Small status indicator or tag | `Badge({ class: "badge-outline" }, "Beta")` |
| **Alert** | Contextual notification | `Alert({ type: "info" }, "Update available")` |
| **Loading** | Loading indicators (spinner, dots) | `Loading({ show: $isLoading })` |
| **Dropdown** | Contextual overlay menu | `Dropdown({ label: "Menu" }, [Link1, Link2])` |
| **Tabs** | Reactive tab-based navigation | `Tabs({ items: ["Home", "Settings"], active: $index })` |
| **Stat** | Statistical data block (KPIs) | `Stat({ label: "Sales", value: "$400" })` |
| **Toast** | Temporary floating notification | `Toast("Done!", "alert-success", 3000)` |

---

## Forms & Inputs

| Component | Description | Example |
| :--- | :--- | :--- |
| **Input** | Text input with floating label, validation, password toggle | `Input({ label: "Email", type: "email", value: $email })` |
| **Select** | Dropdown selector | `Select({ label: "Role", options: ["Admin", "User"], value: $role })` |
| **Autocomplete** | Searchable dropdown with filtering | `Autocomplete({ label: "Country", options: countryList, value: $country })` |
| **Datepicker** | Date picker (single or range mode) | `Datepicker({ label: "Date", value: $date, range: false })` |
| **Colorpicker** | Visual color picker with palette | `Colorpicker({ label: "Theme", value: $color })` |
| **Checkbox** | Checkbox or toggle switch | `Checkbox({ label: "Remember me", value: $remember })` |
| **Radio** | Radio button | `Radio({ label: "Option 1", value: $selected, name: "group" })` |
| **Range** | Slider control | `Range({ label: "Volume", min: 0, max: 100, value: $volume })` |
| **Rating** | Star rating component | `Rating({ value: $stars, count: 5 })` |
| **Swap** | Toggle between two states (sun/moon) | `Swap({ on: "🌞", off: "🌙", value: $isDark })` |

---

## Data Display

| Component | Description | Example |
| :--- | :--- | :--- |
| **Table** | Reactive data grid with columns | `Table({ items: $users, columns: [{ label: "Name", key: "name" }] })` |
| **List** | Vertical list with custom rendering | `List({ items: $items, render: (item) => item.name })` |
| **Badge** | Small status indicators | `Badge({ class: "badge-primary" }, "New")` |
| **Stat** | Statistical data blocks (KPIs) | `Stat({ label: "Total", value: "1.2k", desc: "Monthly" })` |
| **Timeline** | Vertical/horizontal timeline | `Timeline({ items: [{ title: "Step 1", detail: "Completed" }] })` |
| **Stack** | Stacked elements | `Stack({}, [Card1, Card2, Card3])` |
| **Indicator** | Badge on corner of element | `Indicator({ badge: "3" }, Button(...))` |

---

## Feedback & Overlays

| Component | Description | Example |
| :--- | :--- | :--- |
| **Alert** | Inline contextual notification | `Alert({ type: "success" }, "Changes saved!")` |
| **Modal** | Dialog overlay | `Modal({ open: $isOpen, title: "Confirm" }, "Are you sure?")` |
| **Toast** | Floating notification (auto-stacking) | `Toast("Action completed", "alert-info", 3000)` |
| **Loading** | Full-screen or inline loading indicator | `Loading({ show: $isLoading })` |
| **Tooltip** | Hover tooltip wrapper | `Tooltip({ tip: "Help text" }, Button(...))` |

---

## Navigation & Layout

| Component | Description | Example |
| :--- | :--- | :--- |
| **Navbar** | Top navigation bar | `Navbar({}, [Logo, Menu, Avatar])` |
| **Menu** | Vertical navigation menu | `Menu({ items: [{ label: "Home", onclick: goHome }] })` |
| **Drawer** | Side drawer (off-canvas) | `Drawer({ id: "my-drawer", open: $isOpen, content: Main, side: SideMenu })` |
| **Tabs** | Content switching | `Tabs({ items: [{ label: "Tab1", content: Panel1 }] })` |
| **Accordion** | Collapsible sections | `Accordion({ title: "Details" }, "Hidden content")` |
| **Dropdown** | Contextual menus | `Dropdown({ label: "Options" }, [MenuLink("Edit")])` |
| **Fieldset** | Form grouping with legend | `Fieldset({ legend: "Personal Info" }, [Input(...)])` |

---

## Interaction & Utilities

| Component | Description | Example |
| :--- | :--- | :--- |
| **Fab** | Floating Action Button with actions | `Fab({ icon: "+", actions: [{ label: "Add", onclick: add }] })` |
| **Indicator** | Badge indicator wrapper | `Indicator({ badge: "99+" }, Button(...))` |

---

## Internationalization (i18n)

Built-in locale system with Spanish and English support.

```javascript
// Set global UI language
Locale("en"); // or "es"

// Get translated string (returns a reactive signal)
const closeText = tt("close"); // "Close" or "Cerrar"

// Available keys: close, confirm, cancel, search, loading, nodata
```

---

## Implementation Notes

1.  **Atomic Reactivity**: Components accepting `value` or `checked` bind directly to **SigPro Signals**. Updates happen instantly without full page re-renders.

2.  **Tailwind v4 + DaisyUI v5**: Pass any Tailwind utility class via the `class` attribute to override default DaisyUI styling.

    ```javascript
    Button({ class: "btn-primary btn-sm rounded-full shadow-lg" }, "Click")
    ```

3.  **Zero Imports (Global Mode)**: After calling `UI()`, all components are attached to `window`. No manual imports needed.

4.  **Self-Cleaning**: Components internally manage `_cleanups` to destroy observers and event listeners when removed from the DOM.

---

## Advanced Examples

### Reactive Form with Validation

```javascript
const name = $("");
const error = $(null);

Input({
  label: "Full Name",
  value: name,
  error: error,
  oninput: (e) => {
    name(e.target.value);
    error(e.target.value.length < 3 ? "Name too short" : null);
  }
})
```

### API Request Pattern

```javascript
const userId = $("123");
const userData = $(null);
const loading = $(false);

$watch(userId, async (id) => {
  loading(true);
  userData(await fetch(`/api/user/${id}`).then(r => r.json()));
  loading(false);
});

// In template
Loading({ show: loading });
$if(() => userData(), () => Alert({ type: "success" }, userData()?.name))
```

### Modal with Confirm Action

```javascript
const showModal = $(false);

Modal({
  open: showModal,
  title: "Delete Item",
  buttons: [
    Button({ class: "btn-error", onclick: () => { deleteItem(); showModal(false); } }, "Delete")
  ]
}, "Are you sure you want to delete this item?");
```

---

## Component Props Quick Reference

| Component | Key Props |
| :--- | :--- |
| `Button` | `class`, `disabled`, `loading`, `badge`, `tooltip`, `icon` |
| `Input` | `label`, `value`, `error`, `type`, `placeholder`, `disabled`, `tip` |
| `Select` | `label`, `options`, `value`, `disabled` |
| `Modal` | `open`, `title`, `buttons` |
| `Table` | `items`, `columns`, `zebra`, `pinRows`, `empty` |
| `Alert` | `type` (info/success/warning/error), `soft`, `actions` |
| `Toast` | `message`, `type`, `duration` |
| `Loading` | `show` |
| `Datepicker` | `value`, `range`, `label`, `placeholder` |
| `Autocomplete` | `options`, `value`, `onSelect`, `label` |