# SigPro-UI Quick Reference

**Status:** Active / WIP


## Global Initialization

```javascript
import "sigpro-ui";
import "sigpro-ui/css";

// 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 validation | `Input({ value: $name, validate: (v) => !v ? "Required" : "" })` |
| **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")` |
| **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, validate: validateEmail })` |
| **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 })` |

---

## Input Validation

The `Input` component supports real-time validation via the `validate` prop:

```javascript
const email = $('');

Input({
  type: 'email',
  value: email,
  placeholder: 'Enter your email',
  icon: 'icon-[lucide--mail]',
  validate: (value) => {
    if (!value) return '';
    if (!value.includes('@')) return 'Email must contain @';
    if (!value.includes('.')) return 'Email must contain .';
    return '';
  },
  oninput: (e) => email(e.target.value)
})
```

**How it works:**
- Returns `''` or `null` → no error
- Returns a string → shows error message and adds `input-error` class
- Validates on every keystroke
- No external state needed for error messages

---

## 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({ value: () => count() }, 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)` |
| **Tooltip** | Hover tooltip wrapper | `Tooltip({ tip: "Help text", ui: "tooltip-top" }, 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({ value: () => unread() }, Button(...))` |

---

## Internationalization (i18n)

Built-in locale system with Spanish and English support.

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

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

```

---

## Implementation Notes

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

2.  **DaisyUI v5**: Pass any daisyUI styling via the `class` attribute.

    ```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 = $("");

Input({
  value: name,
  placeholder: "Name",
  validate: (value) => {
    if (!value) return "Name is required";
    if (value.length < 3) return "Name too short";
    return "";
  },
  oninput: (e) => name(e.target.value)
})
```

### API Request Pattern

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

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

// In template
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`, `icon` |
| `Input` | `value`, `validate`, `type`, `placeholder`, `icon`, `disabled` |
| `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` |
| `Datepicker` | `value`, `range`, `label`, `placeholder` |
| `Autocomplete` | `options`, `value`, `onSelect`, `label` |
| `Indicator` | `value` (function that returns number/string) |
| `Tooltip` | `tip`, `ui` (tooltip-top/bottom/left/right) |