uploading docs, preview
This commit is contained in:
206
docs/quick.md
Normal file
206
docs/quick.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# 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` |
|
||||
|
||||
Reference in New Issue
Block a user