228 lines
8.1 KiB
Markdown
228 lines
8.1 KiB
Markdown
# 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) |
|